HPAVC/HPAVC CD-ROM.iso/pc/UGPRG.ZIP/PMODE/DPMI100.DOC

Text File | 1995-05-17 | 131.3 KB | 4,058 lines

Int 2FH Function 1680H [1.0]

Release Current Virtual Machine's Time Slice

Called by a client program to indicate that the program is
idle (for example, waiting for keyboard input).  This allows
the DPMI host to pass the CPU to other clients, or take
power-conserving measures on laptop and notebook computers.

Call With:

   AX     = 1680H

Returns:

   if function supported by host
   AL     = 0

   if function not supported by host
   AL     = unchanged (80H)

Notes:

o  This function is not specific to DPMI hosts.  Some
   operating systems will recognize this call for programs
   running in real mode.  Programmers are encouraged to use
   this call in all DOS and DPMI-client programs.  All DPMI
   hosts will hook Int 2FH and so a DPMI client can use this
   API without any other precautions.  Non-DPMI programs
   that can run on DOS 2.xx or earlier should make sure that
   the Int 2FH vector is non-zero before executing the Int
   2FH.

o  When an application calls this function it will regain
   control at intervals, so it should continue to re-issue
   this function call so long as it has nothing to do.

o  DPMI client and application vendors are encouraged to use
   this function.  It can significantly improve the
   performance of a DOS-based multitasking host.
Int 2FH Function 1686H [0.9]

Get CPU Mode

Returns information about the current CPU mode.  Programs
which only execute in protected mode do not need to call
this function.

Call With:

   AX     = 1686H

Returns:

   if executing in protected mode
   AX     = 0

   if executing in real mode or Virtual 86 mode
   AX     = nonzero

Notes:

o  Some environments support programs or libraries that can
   execute in either real or protected mode (bimodal code).
   This function is supplied so that such programs can
   detect at run time whether they are running in protected
   mode and make use of system facilities accordingly.
o  This function should not be used to determine if a DPMI
   host is present.  A client should make sure that DPMI
   services are available before calling this function;
   otherwise, the results returned by the function may not
   be valid.


Int 2FH Function 1687H [0.9]

Obtain Real-to-Protected Mode Switch Entry Point

This function can be called in real mode only to test for
the presence of a DPMI host, and to obtain an address of a
mode switch routine that can be called to begin execution in
protected mode.

Call With:

   AX     = 1687h

Returns:

   if function successful
   AX     = 0
   BX     = flags
           Bit    Significance
           0      0 = 32-bit programs are not supported
                  1 = 32-bit programs are supported
           1-15   not used
   CL     = processor type
           02H = 80286
           03H = 80386
           04H = 80486
           05H-FFH  Reserved for future Intel processors
   DH     = DPMI major version as a decimal number
           (represented in binary)
   DL     = DPMI minor version as a decimal number
           (represented in binary)
   SI     = number of paragraphs required for DPMI host
           private data (may be 0)
   ES:DI  = segment:offset of procedure to call to enter
           protected mode

   if function unsuccessful (no DPMI host present)
   AX     = nonzero

Notes:

o  The entry point returned by Int 2FH Function 1687H is
   only called for the first switch to protected mode by a
   DPMI client.  For further details on the protocol for
   switching to protected mode and the environment after
   switching to protected mode, see page 22.

o  Under DPMI hosts, the major version number is returned in
   DH and the minor version number is returned in DL. There
   are two decimal digits for the minor version number with
   the least-significant digit representing the revision
   number of the minor version number. Under DPMI version
   0.9 hosts, DH is returned as 0, and DL is returned as
   decimal 90 (5AH). In hypothetical DPMI version 2.3, DH
   would be returned as 2 and DL would be returned as 30
   (1EH).



Int 2FH Function 168AH [1.0]

Get Vendor-Specific API Entry Point

Returns an address which can be called to use host-specific
extensions to the standard set of DPMI functions. This
function is available only in protected mode.

Call With:

   AX     = 168AH
   DS:(E)SI= selector:offset of ASCIIZ (null-terminated)
           string identifying the DPMI host vendor

Returns:

   if function successful
   AL     = 0
   ES:(E)DI= extended API entry point

   and DS, FS, GS, EAX, EBX, ECX, EDX, ESI, and EBP are
           preserved.

   if function unsuccessful
   AL     = unchanged (8AH)

Notes:

o  The ASCIIZ string specifies a host vendor name or some
   other unique identifier to obtain a specific extension
   entry point.  The string comparison used to look up the
   API entry point is case-sensitive.
o  Clients must use a FAR CALL to reach the extended API
   entry point.
o  All extended API parameters are specified by the vendor.
o  DPMI 1.0 clients should use this function in preference
   to Int 31H Function 0A00H.  This method of API extension
   is preferable to the Int 31H extension as it avoids the
   creation of a long (and consequently slow) chain of Int
   31H handlers which would slow down time-critical DPMI
   functions. Note that although this function was not
   documented for DPMI 0.9, it will work under any DPMI 0.9
   host.
Int 31H Function 0000H [0.9]

Allocate LDT Descriptors

Allocates one or more descriptors in the task's Local
Descriptor Table (LDT).  The descriptor(s) allocated must be
initialized by the application with other function calls.

Call With:

   AX     = 0000H
   CX     = number of descriptors to allocate

Returns:

   if function successful
   Carry flag= clear
   AX     = base selector

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8011H   descriptor unavailable

Notes:

o  If more than one descriptor was requested, the function
   returns a base selector referencing the first of a
   contiguous array of descriptors.  The selector values for
   subsequent descriptors in the array can be calculated by
   adding the value returned by Int 31H Function 0003H.
o  The allocated descriptor(s) will be set to "data" with
   the present bit set and a base and limit of zero. The
   privilege level of the descriptor(s) will match the
   application's code segment privilege level.

o   Refer to the rules for descriptor usage in Appendix D.

Int 31H Function 0001H [0.9]

Free LDT Descriptor

Frees an LDT descriptor.

Call With:

   AX     = 0001H
   BX     = selector for the descriptor to free

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8022Hinvalid selector

Notes:

o  Each descriptor allocated with Int 31H Function 0000H
   must be freed individually with this function, even if it
   was previously allocated as part of a contiguous array of
   descriptors.
o  Under DPMI 1.0 hosts, any segment registers which contain
   the selector being freed are zeroed by this function.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0002H [0.9]

Segment to Descriptor

Maps a real mode segment (paragraph) address onto an LDT
descriptor that can be used by a protected mode program to
access the same memory.

Call With:

   AX     = 0002H
   BX     = real mode segment address

Returns:

   if function successful
   Carry flag= clear
   AX     = selector for real mode segment

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8011H   descriptor unavailable

Notes:

o  The descriptor's limit will be set to 64 KB.
o  Multiple calls to this function with the same segment
   address will return the same selector.
o  The intent of this function is to provide clients with
   easy access to commonly used real mode segments such as
   the BIOS data area at segment 0040H and the video refresh
   buffers at segments A000H, B000H, and B800H.  Clients
   should not call this function to obtain descriptors to
   private data areas.
o  Descriptors created by this function can never be
   modified or freed.  For this reason, the function should
   be used sparingly.  Clients which need to examine various
   real mode addresses using the same selector should
   allocate a descriptor with Int 31H Function 0000H and
   change the base address in the descriptor as necessary,
   using the Set Segment Base Address function (Int 31H
   Function 0007H).

o   Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0003H [0.9]

Get Selector Increment Value

The DPMI functions Allocate LDT Descriptors (Int 31H
Function 0000H) and Allocate DOS Memory Block (Int 31H
Function 0100H) can allocate
an array of contiguous descriptors, but only return a
selector for the first descriptor.  The value returned by
this function can be used to calculate the selectors for
subsequent descriptors in the array.

Call With:

   AX     = 0003H

Returns:

   Carry flag= clear (this function always succeeds)
   AX     = selector increment value

Notes:

o  The increment value is always a power of two.

Int 31H Function 0004H [0.9]

Reserved

DPMI Function 0004H is reserved for historical reasons and
should not be called.
Int 31H Function 0005H [0.9]

Reserved

DPMI Function 0005H is reserved for historical reasons and
should not be called.
Int 31H Function 0006H [0.9]

Get Segment Base Address

Returns the 32-bit linear base address from the LDT
descriptor for the specified segment.

Call With:

   AX     = 0006H
   BX     = selector

Returns:

   if function successful
   Carry flag= clear
   CX:DX  = 32-bit linear base address of segment

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8022H   invalid selector

Notes:

o  Client programs must use the LSL instruction to query the
   limit for a descriptor.  Note that on 80386 machines, the
   client must use the 32-bit form of LSL if the segment
   size is greater than 64 KB.
o  Refer to the rules for descriptor usage in Appendix D.

Int 31H Function 0007H [0.9]

Set Segment Base Address

Sets the 32-bit linear base address field in the LDT
descriptor for the specified segment.

Call With:

   AX     = 0007H
   BX     = selector
   CX:DX  = 32-bit linear base address of segment

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8022H   invalid selector
           8025H   invalid linear address (changing the base
                   would cause the descriptor to reference a
                   linear address range outside that allowed
                   for DPMI clients)

Notes:

o  A DPMI 1.0 host will automatically reload any segment
   register which contains the selector specified in
   register BX.  It is suggested that DPMI 0.9 hosts also
   implement this.
o  Refer to the rules for descriptor usage in Appendix D.

Int 31H Function 0008H [0.9]

Set Segment Limit

Sets the limit field in the LDT descriptor for the specified
segment.

Call With:

   AX     = 0008H
   BX     = selector
   CX:DX  = 32-bit segment limit

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (CX <> 0 on a 16-bit DPMI
                   host; or the limit is greater than 1 MB,
                   but the low twelve bits are not set)
           8022H   invalid selector
           8025H   invalid linear address (changing the
                   limit would cause the descriptor to
                   reference a linear address range outside
                   that allowed for DPMI clients.)

Notes:

o  The value supplied to the function in CX:DX is the byte
   length of the segment-1 (i.e., the value returned by the
   LSL instruction).
o  Segment limits greater than or equal to 1 MB must be
   page-aligned.  That is, limits greater than 1 MB must
   have the low 12 bits set.
o  This function has an implicit effect on  the "G"
   (granularity) bit in an 80386 descriptor's extended
   access rights/type byte; i.e., it is the host's
   responsibility to set the "G" bit correctly.
o  Client programs must use the LSL instruction to query the
   limit for a descriptor.  Note that on 80386 machines, the
   client must use the 32-bit form of LSL if the segment
   size is greater than 64 KB.
o  A DPMI 1.0 host will reload any segment registers which
   contain the selector specified in register BX.  It is
   suggested that DPMI 0.9 hosts also implement this.
o  Refer to the rules for descriptor usage in Appendix D.

Int 31H Function 0009H [0.9]

Set Descriptor Access Rights

Modifies the access rights and type fields in the LDT
descriptor for the specified segment.

Call With:

   AX     = 0009H
   BX     = selector
   CL     = access rights/type byte
   CH     = 80386 extended access rights/type byte

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (access rights/type bytes
                   invalid)
           8022H   invalid selector
           8025H   invalid linear address (changing the
                   access rights/type bytes would cause the
                   descriptor to reference a linear address
                   range outside that allowed for DPMI
                   clients.)

Notes:

o  The access rights/type byte passed to the function in CL
   has the following format:

   +---+---+---+---+---+---+---+---+
   | P |  DPL  | 1 |C/D|E/C|W/R| A |
   +-+-+---+---+-+-+-+-+-+-+-+-+-+-+
   |     |     |   |   |   |   |
   |     |     |   |   |   |   +- 0=not accessed, 1=accessed
   |     |     |   |   |   +----- data: 0=read,
   1=>read/write
   |     |     |   |   |          code: must be 1 (readable)
   |     |     |   |   +--------- data: 0=expand-up,
   1=expand-down
   |     |     |   |              code: must be 0
   (non-conforming)
   |     |     |   +------------- 0=data, 1=code
   |     |     +----------------- must be 1
   |     +----------------------- must equal caller's CPL
   +----------------------------- 0=absent, 1=present

   If the Present bit is not set in the descriptor, the DPMI
   host allows any values except in the DPL and "must be 1"
   bit fields.

o  On 80386 (and later) machines, the DPMI host interprets
   the value passed to the function in CH as follows:

   +---+---+---+---+---+---+---+---+
   | G |B/D| 0 |Avl|    Reserved   |
   +-+-+-+-+-+-+-+-+---+---+---+---+
   |   |   |   |         |
   |   |   |   |         +-- ignored
   |   |   |   +------------ can be 0 or 1
   |   |   +---------------- must be 0
   |   +-------------------- 0=default 16-bit, 1=default
   32-bit
   +------------------------ 0=byte granular, 1=page
   granular

o  A DPMI 1.0 host will reload any segment registers which
   contain the selector specified in register BX. It is
   suggested that DPMI 0.9 hosts also implement this.
o  Client programs should use the LAR instruction to examine
   the access rights of a descriptor.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000AH [0.9]

Create Alias Descriptor

Creates a new LDT data descriptor that has the same base and
limit as the specified descriptor.

Call With:

   AX     = 000AH
   BX     = selector

Returns:

   if function successful
   Carry flag= clear
   AX     = data selector (alias)

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8011H  descriptor unavailable
           8022H  invalid selector

Notes:

o  The selector supplied to the function may be either a
   data selector or an executable selector. Note that the
   published 0.9 specification was in error to say that the
   function generates an error on a data descriptor.
o  The descriptor alias returned by this function will not
   track changes to the original descriptor.  In other
   words, if an alias is created with this function, and the
   base or limit of the original segment is then changed,
   the two descriptors will no longer map the same memory.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000BH [0.9]

Get Descriptor

Copies the local descriptor table (LDT) entry for the
specified selector into an 8-byte buffer.

Call With:

   AX     = 000BH
   BX     = selector
   ES:(E)DI= selector:offset of 8-byte buffer

Returns:

   if function successful
   Carry flag= clear

   and buffer pointed to by ES:(E)DI contains descriptor
   if function unsuccessful
   Carry flag= set
   AX     = error code
           8022H   invalid selector

Notes:

o  32-bit programs must use ES:EDI to point to the buffer.
   16-bit programs should use ES:DI.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000CH [0.9]

Set Descriptor

Copies the contents of an 8-byte buffer into the LDT
descriptor for the specified selector.

Call With:

   AX     = 000CH
   BX     = selector
   ES:(E)DI= selector:offset of 8-byte buffer containing
           descriptor

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (access rights/type byte
                   invalid)
           8022H   invalid selector
           8025H   invalid linear address (descriptor
                   references a linear address range outside
                   that allowed for DPMI clients)

Notes:

o  32-bit programs must use ES:EDI to point to the buffer.
   16-bit programs should use ES:DI.
o  The descriptor's access rights/type byte (byte 5) follows
   the same format and restrictions as the access
   rights/type parameter (in CL) for the Set Descriptor
   Access R
ights function (Int 31H Function 0009H).  On 80386 (or later)
   machines, the descriptor's extended access rights/type
   byte (byte 6) follows the same format and restrictions as
   the extended access rights/type parameter (in CH) for the
   same function, except the low-order 4 bits (marked
   "reserved") are used to set the upper 4 bits of the
   descriptor's limit.
o  If the descriptor's present bit is not set, then the only
   error checking is that the client's CPL must be equal to
   the descriptor's DPL field and the "must be 1" bit in the
   descriptor's byte 5 must be set.
o  A DPMI 1.0 host will reload any segment register which
   contains a selector specified in register BX.  It is
   suggested that DPMI 0.9 hosts also implement this.

o  Refer to the rules for descriptor usage in Appendix D.

Int 31H Function 000DH [0.9]

Allocate Specific LDT Descriptor

Allocates a specific LDT descriptor.

Call With:

   AX     = 000DH
   BX     = selector

Returns:

   if function successful
   Carry flag= clear

   and descriptor has been allocated
   if function unsuccessful
   Carry flag= set
   AX     = error code
           8011H   descriptor unavailable (descriptor is in
                   use)
           8022H   invalid selector (references GDT or
                   beyond the LDT limit)

Notes:

o  The first 10H (16) descriptors (selector values 04H-7CH)
   are reserved for this function and must not be used by
   the DPMI host.
o  Under DPMI 0.9 hosts, if another application has already
   been loaded, some of descriptors reserved for allocation
   by this function may be already in use and unavailable.
   Under DPMI 1.0 hosts, each client has its own LDT and
   thus will have the full 16 descriptors available for use
   with this function.
o  Resident service providers (protected-mode TSRs) should
   not use this function.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000EH [1.0]

Get Multiple Descriptors

Copies one or more local descriptor table (LDT) entries into
a client buffer.

Call With:

   AX     = 000EH
   CX     = number of descriptors to copy
   ES:(E)DI= selector:offset of a buffer in the following
           format:

           Offset   Length   Contents
           00H      2        Selector #1 (set by client)
           02H      8        Descriptor #1 (returned by
           host)
           0AH      2        Selector #2 (set by client)
           0CH      8        Descriptor #2 (returned by
           host)
           .        .        .
           .        .        .
           .        .        .

Returns:

   if function successful
   Carry flag= clear

   and buffer contains copies of the descriptors for the
   specified selectors

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8022H   invalid selector
   CX     = number of descriptors successfully copied

Notes:

o  If an error occurs because of an invalid selector or
   descriptor, the function returns the number of
   descriptors which were successfully copied in CX.  All of
   the descriptors which were copied prior to the one that
   failed are valid.
o  32-bit programs must use ES:EDI to point to the buffer.
   16-bit programs should use ES:DI.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000FH [1.0]

Set Multiple Descriptors

Copies one or more descriptors from a client buffer into the
local descriptor table (LDT).

Call With:

   AX     = 000FH
   CX     = number of descriptors to copy
   ES:(E)DI= selector:offset of a buffer in the following
           format:

           Offset   Length   Contents
           00H      2        Selector #1
           02H      8        Descriptor #1
           0AH      2        Selector #2
           0CH      8        Descriptor #2
           .        .        .
           .        .        .
           .        .        .

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (access rights/type bytes
                   invalid)
           8022H   invalid selector 8025H    invalid linear
                   address (descriptor references a linear
                   address range outside that allowed for
                   DPMI clients)
   CX     = number of descriptors successfully copied

Notes:

o  If an error occurs because of an invalid selector or
   descriptor, the function returns the number of
   descriptors which were successfully copied in CX.  All of
   the descriptors which were copied prior to the one that
   failed are valid.  All descriptors from the invalid entry
   to the end of the table are not updated.
o  32-bit programs must use ES:EDI to point to the buffer.
   16-bit programs should use ES:DI.
o  A descriptor's access rights/type byte (byte 5) follows
   the same format and restrictions as the access
   rights/type parameter (in CL) for the Set Descriptor
   Access Rights function (Int 31H Function 0009H).  On
   80386 (or later) machines, the descriptor's extended
   access rights/type byte (byte 6) follows the same format
   and restrictions as the extended access rights/type
   parameter (in CH) for the same function, except the
   low-order 4 bits (marked "reserved") are used to set the
   upper 4 bits of the descriptor's limit.
o  If the descriptor's present bit is not set, then the only
   error checking is that the client's CPL must be equal to
   the descriptor's DPL field and the "must be 1" bit in the
   descriptor's byte 5 must be set.
o  A DPMI 1.0 host will reload any segment register which
   contains a selector specified in the data structure
   supplied to this function.  It is suggested that DPMI 0.9
   hosts also implement this.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0100H [0.9]

Allocate DOS Memory Block

Allocates a block of memory from the DOS memory pool, i.e.
memory below the 1 MB boundary that is controlled by DOS.
Such memory blocks are typically used to exchange data with
real mode programs, TSRs, or device drivers.  The function
returns both the real mode segment base address of the block
and one or more descriptors that can be used by protected
mode applications to access the block.

Call With:

   AX     = 0100H
   BX     = number of (16-byte) paragraphs desired

Returns:

   if function successful
   Carry flag= clear
   AX     = real mode segment base address of allocated
           block
   DX     = selector for allocated block

   if function unsuccessful
   Carry flag= set
   AX     = error code
           0007H   memory control blocks damaged (also
                   returned by DPMI 0.9 hosts)
           0008H   insufficient memory (also returned by
                   DPMI 0.9 hosts).
           8011H   descriptor unavailable
   BX     = size of largest available block in paragraphs

Notes:

o  If the size of the block requested is greater than 64 KB
   (BX > 1000H) and the client is a 16-bit program,
   contiguous descriptors are allocated and the base
   selector is returned.  The consecutive selectors for the
   memory block can be calculated using the value returned
   by the Get Selector Increment Value function (Int 31H
   Function 0003H).  Each descriptor has a limit of 64 KB,
   except for the last which has a limit of blocksize MOD 64
   KB.
o  If the DPMI host is 32-bit, the client is 16-bit, and
   more than one descriptor is allocated, the limit of the
   first descriptor will be set to the size of the entire
   block.  Subsequent descriptors have limits as described
   in the previous Note. 16-bit DPMI hosts will always set
   the limit of the first descriptor to 64 KB even when
   running on an 80386 (or later) machine.
o  When the client is 32-bit, this function always allocates
   only one descriptor.
o  Client programs should never modify or free any
   descriptors allocated by this function.  The Free DOS
   Memory Block function (Int 31H Function 0101H) will
   deallocate the descriptors automatically.
o  The DOS allocation function (Int 21H Function 48H) is
   used.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0101H [0.9]

Free DOS Memory Block

Frees a memory block that was previously allocated with the
Allocate DOS Memory Block function (Int 31H Function 0100H).

Call With:

   AX     = 0101H
   DX     = selector of block to be freed

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           0007H   memory control blocks damaged (also
                   returned by DPMI 0.9 hosts).
           0009H   incorrect memory segment specified (also
                   returned by DPMI 0.9 hosts).
           8022H   invalid selector

Notes:

o  All descriptors allocated for the memory block are
   automatically freed by this function, and are no longer
   valid after this function returns.
o  Under DPMI 1.0 hosts, any segment registers which contain
   a selector being freed are zeroed by this function.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0102H [0.9]

Resize DOS Memory Block

Changes the size of a memory block that was previously al
located with the Allocate DOS Memory Block function (Int 31H
Function 0100H).

Call With:

   AX     = 0102H
   BX     = new block size in (16-byte) paragraphs
   DX     = selector of block to modify

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           0007H   memory control blocks damaged (also
                   returned by DPMI 0.9 hosts).
           0008H   insufficient memory (also returned by
                   DPMI 0.9 hosts).
           0009H   incorrect memory segment specified (also
                   returned by DPMI 0.9 hosts).
           8011H   descriptor unavailable
           8022H   invalid selector
   BX     = maximum possible block size (paragraphs)

Notes:

o  Requests to increase the size of an existing DOS memory
   block may fail due to subsequent DOS memory block
   allocations causing fragmentation of DOS memory, or
   insufficient remaining DOS memory.  In addition, the
   function will fail if the block is growing past a 64 KB
   boundary and the next descriptor in the LDT is not
   available.
o  A request to decrease the size of a DOS memory block may
   cause some descriptors that were previously allocated to
   the block to be freed and the limit of the new last
   descriptor for the block to be changed.
o  Under a DPMI 1.0 host, any segment registers which
   contain a selector being modified are reloaded by this
   function and any segment registers which contain a
   selector being freed are zeroed by this function.
o  Client programs should never modify or free any
   descriptors allocated by this function.  The Free DOS
   Memory Block function (Int 31H Function 0101H) will
   deallocate the descriptors automatically.
o  Refer to the rules for descriptor usage in Appendix D.

Int 31H Function 0200H [0.9]

Get Real Mode Interrupt Vector

Returns the contents of the current virtual machine's real
mode interrupt vector for the specified interrupt.

Call With:

   AX     = 0200H
   BL     = interrupt number

Returns:

   Carry flag= clear (this function always succeeds)
   CX:DX  = segment:offset of real mode interrupt handler

Notes:

o  The value returned in CX is a real mode segment address,
   not a selector.  Attempts to place this value into a
   segment register in protected mode may cause a general
   protection (GP) fault.
o  All 100H (256) real mode interrupt vectors must be made
   available through this function by the DPMI host.
Int 31H Function 0201H [0.9]

Set Real Mode Interrupt Vector

Sets the current virtual machine's real mode interrupt
vector for the specified interrupt.

Call With:

   AX     = 0201H
   BL     = interrupt number
   CX:DX  = segment:offset of real mode interrupt handler

Returns:

   Carry flag= clear (this function always succeeds)

Notes:

o  The address passed in CX must be a real mode segment
   address, not a selector.  Consequently, the interrupt
   handler must either reside in DOS memory (i.e. below the
   1 MB boundary) or the client must allocate a real mode
   callback address.  See Int 31H Functions 0100H and 0303H.
o  If the interrupt being hooked is a hardware interrupt,
   the memory  that the interrupt handler uses must be
   locked.

Int 31H Function 0202H [0.9]

Get Processor Exception Handler Vector

Returns the address of the current client's protected mode
exception handler for the specified exception number.  This
function should be avoided by DPMI 1.0 clients (see Notes).

Call With:

   AX     = 0202H
   BL     = exception number (00H-1FH)

Returns:

   if function successful
   Carry flag= clear
   CX:(E)DX= selector:offset of exception handler

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (BL not in range 0-1FH)

Notes:

o  The value returned in CX is a valid protected mode
   selector, not a real mode segment address.
o  32-bit clients will be returned a 32-bit offset in the
   EDX register.
o  Clients which run under DPMI 1.0 should use Int 31H
   Functions 0210H and 0211H to obtain the addresses of
   exception handlers.  This function is supported by DPMI
   1.0 hosts solely for compatibility with DPMI 0.9.
Int 31H Function 0203H [0.9]

Set Processor Exception Handler Vector

Sets the address of a handler for a CPU exception or fault,
allowing a protected mode application to intercept processor
exceptions (such as segment not present faults) that are not
handled by the DPMI host and would otherwise generate a
fatal error.  This function should be avoided by DPMI 1.0
clients (see Notes).

Call With:

   AX     = 0203H
   BL     = exception/fault number (00H-1FH)
   CX:(E)DX= selector:offset of exception handler

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (BL not in range 0-1FH)
           8022H   invalid selector

Notes:

o  The value passed in CX should  be a valid protected mode
   code (executable) selector, not a real mode segment
   address.
o  32-bit clients must supply a 32-bit offset in the EDX
   register.  If the client's handler chains to the next
   exception handler, it must do so using a 32-bit interrupt
   stack frame.
o  Every exception is first examined by the DPMI host.  If
   the host does not handle the exception, it reflects the
   exception to the first handler in the protected mode
   exception handler chain.  See page 30 for a complete
   discussion of the environment and responsibilities of
   protected mode exception handlers installed with this
   function.
o  Clients which run under DPMI 1.0 should use Int 31H
   Functions 0212H and 0213H to set the addresses of
   exception handlers.  This function is supported by DPMI
   1.0 hosts solely for compatibility with DPMI 0.9.
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0204H [0.9]

Get Protected Mode Interrupt Vector

Returns the address of the current protected mode interrupt
handler for the specified interrupt.

Call With:

   AX     = 0204H
   BL     = interrupt number

Returns:

   Carry flag= clear (this function always succeeds)
   CX:(E)DX= selector:offset of exception handler

Notes:

o  The value returned in CX is a valid protected mode
   selector, not a real mode segment address.
o  32-bit clients will be returned a 32-bit offset in the
   EDX register.
o  DPMI hosts must make all 100H (256) interrupt vectors
   available through this function.
Int 31H Function 0205H [0.9]

Set Protected Mode Interrupt Vector

Sets the address of protected mode handler for the specified
interrupt into the interrupt vector.

Call With:

   AX     = 0205H
   BL     = interrupt number
   CX:(E)DX= selector:offset of exception handler

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8022H   invalid selector

Notes:

o  The value passed in CX  should be a valid protected mode
   code selector, not a real mode segment address.
o  32-bit clients must supply a 32-bit offset in the EDX
   register.  If the client's handler chains to the next
   exception handler it must do so using a 32-bit interrupt
   stack frame.
o  DPMI hosts must support all 100H (256 decimal) interrupt
   vectors with this function.
o  Hardware interrupts are sent to the primary client of the
   virtual machine while software interrupts are sent to the
   current client. (See Appendix A: Glossary for definitions
   of primary and current client.)
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0210H [1.0]

Get Extended Processor Exception Handler Vector
(Protected Mode)

Returns the address of the client's protected mode handler
for the specified protected mode exception.

Call With:

   AX     = 0210H
   BL     = exception number (00H-1FH)

Returns:

   if function successful
   Carry flag= clear
   CX:(E)DX= selector:offset of exception handler

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (BL not in range 00H-1FH)

Notes:

o  DPMI 1.0 clients should use this function in preference
   to Int 31H Function 0202H.
o  The protected mode exceptions are sent to the protected
   mode handler of the current client. (See Appendix A:
   Glossary for definition of primary client.)

Int 31H Function 0211H [1.0]

Get Extended Processor Exception Handler Vector
(Real Mode)

Returns the address of the client's protected mode handler
for the specified real mode exception.

Call With:

   AX     = 0211H
   BL     = exception number (00H-1FH)

Returns:

   if function successful
   Carry flag= clear
   CX:(E)DX= selector
   :offset of exception handler

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (BL not in range 00H-1FH)

Notes:

o  CX:(E)DX does not specify a real-mode segment:offset.
   The reason is that this function allows a client to get
   the address of the exception handler which will receive
   control in protected mode when the specified exception
   occurs in real mode (i.e. the host will provide an
   implied mode switch for the purposes of servicing the
   exception, then return to real mode after  the handler
   exits)..
o  Real mode exceptions are sent to the primary client of
   the virtual machine.



Int 31H Function 0212H [1.0]

Set Extended Processor Exception Handler Vector
(Protected Mode)

Sets the address of the client's protected mode handler for
the specified protected mode exception.

Call With:

   AX     = 0212H
   BL     = exception/fault number (00H-1FH)
   CX:(E)DX= selector:offset of exception handler

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (BL not in range 00H-1FH)
           8022H   invalid selector

Notes:

o  DPMI 1.0 clients should use this function in preference
   to Int 31H Function 0203H.
o  The protected mode exceptions are sent to the protected
   mode handler of the current client.
o  Refer to the rules for descriptor usage in Appendix D.


Int 31H Function 0213H [1.0]

Set Extended Processor Exception Handler Vector
(Real Mode)

Sets the address of the client's protected mode handler for
the specified real mode exception.

Call With:

   AX     = 0213H
   BL     = exception/fault number (00H-1FH)
   CX:(E)DX= selector:offset of exception handler

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (BL not in range 00H-1FH)
           8022H   invalid selector

Notes:

o  CX:(E)DX does not specify a real-mode segment:offset.
   The reason is that this function allows a client to set
   the address of an exception handler which will receive
   control in protected mode when the specified exception
   occurs in real mode (i.e. the host will provide an
   implied mode switch for the purposes of servicing the
   exception, then return to real mode after  the handler
   exits).
o  Real mode exceptions are sent to the primary client of
   the virtual machine. (See Appendix A: Glossary for
   definition of primary client.)
o  Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0300H [0.9]

Simulate Real Mode Interrupt

Simulates an interrupt in real mode.  The function transfers
control to the address specified by the real mode interrupt
vector.  The real mode handler must return by executing an
IRET.

Call With:

   AX     = 0300H
   BL     = interrupt number
   BH     = flags
           Bit    Significance
           0      reserved for historical reason, must be
           zero
           1-7    reserved, must be zero
   CX     = number of words to copy from protected mode to
           real mode stack
   ES:(E)DI= selector:offset of real mode register data
           structure in the following format:

           Offset   Length  Contents
           00H      4       DI or EDI
           04H      4       SI or ESI
           08H      4       BP or EBP
           0CH      4       reserved, should be zero
           10H      4       BX or EBX
           14H      4       DX or EDX
           18H      4       CX or ECX
           1CH      4       AX or EAX
           20H      2       CPU status flags
           22H      2       ES
           24H      2       DS
           26H      2       FS
           28H      2       GS
           2AH      2       IP (reserved, ignored)
           2CH      2       CS (reserved, ignored)
           2EH      2       SP
           30H      2       SS

Returns:

   if function successful
   Carry flag= clear
   ES:(E)DI= selector:offset of modified real mode register
           data structure

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8012H   linear memory unavailable (stack)
           8013H   physical memory unavailable (stack)
           8014H   backing store unavailable (stack)
           8021H   invalid value (CX too large)


Notes:

o  32-bit programs must use ES:EDI to point to the real mode
   register data structure.  16-bit programs should use
   ES:DI.
o  The CS:IP in the real mode register data structure is
   ignored by this function.  The appropriate interrupt
   handler will be called based on the value passed in BL.
o  If the SS:SP fields in the real mode register data
   structure are zero, a real mode stack will be provided by
   the DPMI host.  Otherwise, the real mode SS:SP will be
   set to the specified values before the interrupt handler
   is called.
o  The flags specified in the real mode register data
   structure will be pushed on the real mode stack's IRET
   frame.  The interrupt handler will be called with the
   interrupt and trace flags clear.
o  Values placed in the segment register positions of the
   data structure must be valid for real mode; i.e. the
   values must be paragraph addresses and not selectors.
o  All general register fields in the data structure are
   DWORDs so that 32-bit registers can be passed to real
   mode.  Note, however, that 16-bit hosts are not required
   to pass the high word of 32-bit general registers or the
   FS and GS segment registers to real mode even when
   running on an 80386 or later CPU.
o  The target real mode handler must return with the stack
   in the same state as when it was called.  This means that
   the real mode code may switch stacks while it is running,
   but must return on the same stack that it was called on
   and  must return with an IRET.
o  When this function returns, the real mode register data
   structure will contain the values that were returned by
   the real mode interrupt handler.
o  It is the caller's responsibility to remove any
   parameters that were pushed on the protected mode stack.
Int 31H Function 0301H [0.9]

Call Real Mode Procedure With Far Return Frame

Simulates a FAR CALL to a real mode procedure.  The called
procedure must return by executing a RETF (far return)
instruction.

Call With:

   AX     = 0301H
   BH     = flags
           Bit    Significance
           0      reserved for historical reason, must be
           zero
           1-7    reserved, must be zero
   CX     = number of words to copy from protected mode to
           real mode stack
   ES:(E)DI= selector:offset of real mode register data
           structure in the following format:

           Offset   Length  Contents
           00H      4       DI or EDI
           04H      4       SI or ESI
           08H      4       BP or EBP
           0CH      4       reserved, ignored
           10H      4       BX or EBX
           14H      4       DX or EDX
           18H      4       CX or ECX
           1CH      4       AX or EAX
           20H      2       CPU status flags
           22H      2       ES
           24H      2       DS
           26H      2       FS
           28H      2       GS
           2AH      2       IP
           2CH      2       CS
           2EH      2       SP
           30H      2       SS

Returns:

   if function successful
   Carry flag= clear
   ES:(E)DI= selector:offset of modified real mode register
           data structure

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8012H   linear memory unavailable (stack)
           8013H   physical memory unavailable (stack)
           8014H   backing store unavailable (stack)
           8021H   invalid value (CX too large)




Notes:

o  32-bit programs must use ES:EDI to point to the real mode
   register data structure.  16-bit programs should use
   ES:DI.
o  The CS:IP in the real mode register data structure
   specifies the address of the real mode procedure to call.
o  If the SS:SP fields in the real mode register data
   structure are zero, a real mode stack will be provided by
   the DPMI host.  Otherwise, the real mode SS:SP will be
   set to the specified values before the interrupt handler
   is called.
o  Values placed in the segment register positions of the
   data structure must be valid for real mode; i.e. the
   values must be paragraph addresses and not selectors.
o  All general register fields in the data structure are
   DWORDs so that 32-bit registers can be passed to real
   mode.  Note, however, that 16-bit hosts are not required
   to pass the high word of 32-bit general registers or the
   FS and GS segment registers to real mode even when
   running on an 80386 or later CPU.
o  The target real mode procedure must return with the stack
   in the same state as when it was called.  This means that
   the real mode code may switch stacks while it is running,
   but must return on the same stack that it was called on
   and must exit with a RETF (far return) and should not
   clear the stack of any other parameters that were passed
   to it on the stack.
o  When this function returns, the real mode register data
   structure will contain the values that were returned by
   the real mode procedure.
o  It is the caller's responsibility to remove any
   parameters that were pushed on the protected mode stack.
Int 31H Function 0302H [0.9]

Call Real Mode Procedure With IRET Frame

Simulates a FAR CALL w
ith flags pushed on the stack to a real mode procedure.  The
real mode routine must return by executing an IRET
instruction.

Call With:

   AX     = 0302H
   BH     = flags
           Bit    Significance
           0      reserved for historical reason, must be
           zero
           1-7    reserved, must be zero
   CX     = number of words to copy from protected mode to
           real mode stack
   ES:(E)DI= selector:offset of real mode register data
           structure in the following format:

           Offset   Length  Contents
           00H      4       DI or EDI
           04H      4       SI or ESI
           08H      4       BP or EBP
           0CH      4       reserved, ignored
           10H      4       BX or EBX
           14H      4       DX or EDX
           18H      4       CX or ECX
           1CH      4       AX or EAX
           20H      2       CPU status flags
           22H      2       ES
           24H      2       DS
           26H      2       FS
           28H      2       GS
           2AH      2       IP
           2CH      2       CS
           2EH      2       SP
           30H      2       SS

Returns:

   if function successful
   Carry flag= clear
   ES:(E)DI= selector:offset of modified real mode register
           data structure

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8012H   linear memory unavailable (stack)
           8013H   physical memory unavailable (stack)
           8014H   backing store unavailable (stack)
           8021H   invalid value (CX too large)




Notes:

o  32-bit programs must use ES:EDI to point to the real mode
   register data structure.  16-bit programs should use
   ES:DI.
o  The CS:IP in the real mode register data structure
   specifies the address of the real mode procedure to call.
o  If the SS:SP fields in the real mode register data
   structure are zero, a real mode stack will be provided by
   the DPMI host.  Otherwise, the real mode SS:SP will be
   set to the specified values before the interrupt handler
   is called.
o  The flags specified in the real mode register data
   structure will be pushed on the real mode stack's IRET
   frame.  The procedure will be called with the interrupt
   and trace flags clear.
o  Values placed in the segment register positions of the
   data structure must be valid for real mode; i.e. the
   values must be paragraph addresses and not selectors.
o  All general register fields in the data structure are
   DWORDs so that 32-bit registers can be passed to real
   mode.  Note, however, that 16-bit hosts are not required
   to pass the high word of 32-bit general registers or the
   FS and GS segment registers to real mode even when
   running on an 80386 or later CPU.
o  The target real mode handler or procedure must return
   with the stack in the same state as when it was called.
   This means that the real mode code may switch stacks
   while it is running, but must return on the same stack
   that it was called on and must return with an IRET or
   discard the flags from the stack with a RETF(2) .
o  When this function returns, the real mode register data
   structure will contain the values that were returned by
   the real mode procedure.
o  It is the caller's responsibility to remove any
   parameters that were pushed on the protected mode stack.
Int 31H Function 0303H [0.9]

Allocate Real Mode Callback Address

Returns a unique real mode segment:offset, known as a "real
mode callback,"  that will transfer control from real mode
to a protected mode procedure.  Callback addresses obtained
with this function can be passed by a protected mode program
to a real mode application, interrupt handler, device
driver, or TSR, so that the real mode program can call
procedures within the protected mode program or notify the
protected mode program of an event.

Call With:

   AX     = 0303H
   DS:(E)SI= selector:offset of protected mode procedure to
           call
   ES:(E)DI= selector:offset of 32H-byte buffer for real
           mode register data structure to be used when
           calling callback routine.

Returns:

   if function successful
   Carry flag= clear
   CX:DX  = segment:offset of real mode callback

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8015H   callback unavailable

Notes:

o  DPMI hosts must provide a minimum of 16 callback
   addresses per client.
o  A descriptor may be allocated for each callback to hold
   the real mode SS descriptor. Real mode callbacks are a
   limited system resource.  A client should use the Free
   Real Mode Callback Address function (Int 31H Function
   0304H) to release a callback that it is no longer using.
o  For further information on writing real mode callback
   procedures, see page 34.
o  The contents of the real mode register data structure is
   not valid after the function call, but only at the time
   of the actual callback.

Int 31H Function 0304H [0.9]

Free Real Mode Callback Address

Releases a real mode callback address that was previously
allocated with the Allocate Real Mode Callback Address
function (Int 31H Function 0303H).

Call With:

   AX     = 0304H
   CX:DX  = real mode callback address to be freed

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8024H   invalid callback address

Notes:

o  Real mode callbacks are a limited system resource.  A
   client should release any callback that it is no longer
   using.
Int 31H Function 0305H [0.9]

Get State Save/Restore Addresses

Returns the addresses of two procedures used to save and
restore the state of the current task's registers in the
mode which is not currently executing.

Call With:

   AX     = 0305H

Returns:

   Carry flag = clear (this function always succeeds)
   AX     = size of buffer in bytes required to save state
   BX:CX  = real mode address of routine used to
           save/restore state
   SI:(E)DI= protected mode address of routine used to
           save/restore state

Notes:

o  The real mode address returned by this function in BX:CX
   is called only in real mode to save/restore the state of
   the protected mode registers.  The protected mode address
   returned by this function in SI:(E)DI  is called only in
   protected mode to save/restore the state of the real mode
   registers; 16-bit programs should call the address in
   SI:DI, 32-bit programs should call the address in SI:EDI.
   Registers for the current mode can be saved by simply
   pushing them on the stack.
o  Both of the state-save procedures are entered by a FAR
   CALL with the following parameters:

AL = 0 to save state
   = 1 to restore state
ES:(E)DI= (selector or segment):offset of state-save buffer

The state-save buffer must be at least as large as the value returned
   in AX by Int 31H Function 0305H.  The state save/restore
   procedures do not modify any registers.  For a further
   discussion of use of the state save/restore procedures,
   see page 25.
o  Some DPMI hosts will not require the state to be saved,
   indicating this by returning a buffer size of zero in AX.
   In such cases, the addresses returned by this function
   can still be called, although they will simply return
   without performing any useful function.
o  Clients do not need to call the state save/restore
   procedures before using Int 31H Functions 0300H, 0301H,
   or 0302H.  The state save/restore procedures are provided
   specifically for clients that use the raw mode switch
   services.
o  A client can use the function to save its state in the
   destination mode before switching modes using the raw
   mode switch or issuing real-mode calls from a protected
   mode hardware interrupt handler. Refer to page 24 for the
   detailed information on stacks and mode switching.
Int 31H Function 0306H [0.9]

Get Raw Mode Switch Addresses

Returns addresses that can be called for low-level mode
switching.

Call With:

   AX     = 0306H

Returns:

   Carry flag = clear (this function always succeeds)
   BX:CX  = real-to-protected mode switch address
   SI:(E)DI= protected-to-real mode switch address

Notes:

o  The address returned in BX:CX must only be called in real
   mode to switch into protected mode.  The address returned
   in SI:(E)DI must only be called in protected mode to
   switch into real mode; 16-bit programs should call the
   address returned by this function in SI:DI, while 32-bit
   programs should call the address returned in SI:EDI.

o  The mode switch procedures are entered by a FAR JMP to
   the appropriate address with the following parameters:

AX = new DS
CX = new ES
DX = new SS
(E)BX= new (E)SP
SI = new CS
(E)DI= new (E)IP

The processor is placed into the desired mode, and the DS, ES, SS,
   (E)SP, CS, and (E)IP registers are updated with the
   specified values; in other words, execution of the client
   continues in the requested mode at the address provided
   in registers SI:(E)DI.  The values specified to be placed
   into th
e segment registers must be appropriate for the destination mode; if
   invalid selectors are supplied when switching into
   protected mode, an exception will occur.

The values in (E)AX, (E)BX, (E)CX, (E)DX, (E)SI, and (E)DI after the
   mode switch are undefined. (E)BP will be preserved across
   the mode switch call so it can be used as a pointer. On
   an 80386 or later CPU, the FS and GS segment registers
   will contain zero after the mode switch.

If interrupts are disabled when the mode switch procedure is invoked,
   they will not be re-enabled by the DPMI host (even
   temporarily).

o  It is up to the client to save and restore the state of
   the task when using this function to switch modes.  This
   usually requires using the state save/restore procedures
   whose addresses are returned by Int 31H Function 0305H
   (see page 94).

o  Clients may find it more convenient to use Int 31H
   Functions 0300H, 0301H, and 0302H for mode switching than
   this function.

Int 31H Function 0400H [0.9]

Get Version

Returns the version number of the DPMI Specification
implemented by the DPMI host.  Clients can use this
information to determine which function calls are supported
in the current environment.

Call With:

   AX     = 0400H

Returns:

   Carry flag= clear (this function always succeeds)
   AH     = DPMI major version as a  binary number
   AL     = DPMI minor version as a  binary number
   BX     = flags
           Bits   Significance
           0      0 = host is 16-bit DPMI implementation
                  1 = host is 32-bit (80386) DPMI
           implementation
           1      0 = CPU returned to Virtual 86 mode for
           reflected interrupts
                  1 = CPU returned to real mode for
           reflected interrupts
           2      0 = virtual memory not supported
                  1 = virtual memory supported
           3      reserved, for historical reasons
           4-15   reserved for later use
   CL     = processor type
           02H = 80286
           03H = 80386
           04H = 80486
           05H-FFH       reserved for future Intel
           processors
   DH     = current value of virtual master PIC base
           interrupt
   DL     = current value of virtual slave PIC base
           interrupt

Notes:

o  Under DPMI hosts, the major version number is returned in
   DH and the minor version number is returned in DL. There
   are two decimal digits for the minor version number with
   the least-significant digit representing the revision
   number of the minor version number. Under DPMI version
   0.9 hosts, DH is returned as 0, and DL is returned as
   decimal 90 (5AH). In hypothetical DPMI version 2.3, DH
   would be returned as 2 and DL would be returned as 30
   (1EH).


Int 31H Function 0401H [1.0]

Get DPMI Capabilities

Returns information about the capabilities of the DPMI host,
including its support or lack of support for optional
features in the DPMI Specification.  Clients can use this
information to optimize their use of system resources in the
current environment.

Call With:

   AX     = 0401H
   ES:(E)DI= selector:offset of 128-byte buffer

Returns:

   if function successful
   Carry flag= clear (this function always succeeds in DPMI
           1.0)
   AX     = capabilities flags

           Bits   Significance
           0      0 = PAGED ACCESSED/DIRTY capability not
           supported
                  1 = PAGED ACCESSED/DIRTY capability
           supported
           1      0 = EXCEPTIONS RESTARTABILITY capability
           not supported
                  1 = EXCEPTIONS RESTARTABILITY capability
           supported
           2      0 = DEVICE MAPPING capability not
           supported
                  1 = DEVICE MAPPING capability supported
           3      0 = CONVENTIONAL MEMORY MAPPING
                     capability not supported
                  1 = CONVENTIONAL MEMORY MAPPING
           capability supported
           4      0 = DEMAND ZERO-FILL capability not
           supported
                  1 = DEMAND ZERO-FILL capability supported
           5      0 = WRITE-PROTECT CLIENT capability not
           supported
                  1 = WRITE-PROTECT CLIENT capability
           supported
           6      0 = WRITE-PROTECT HOST capability not
           supported
                  1 = WRITE-PROTECT HOST capability
           supported
           7-15   reserved
   CX     = reserved, must be 0
   DX     = reserved, must be 0
   ES:(E)DI = selector:offset of 128-byte buffer filled in
           by host with information as follows:

           Offset   Length   Contents
           0        1        Host major version number as a
           decimal number
           1        1        Host minor version number as a
           decimal number
           2        1-126    ASCIIZ (null-terminated) string
                             identifying the DPMI host
                             vendor

   if function unsuccessful
   Carry flag= set (this function always fails in DPMI 0.9)

Notes:

o  PAGE ACCESSED/DIRTY capability means the DPMI host
   maintains page dirty and accessed bits that can be read
   and written with the Get and Set Page Attributes
   functions (Int 31H Functions 0506H and 0507H).  This
   capability must be supported, and must read and write the
   hardware-level dirty and accessed bits, if the DPMI host
   does not provide demand-paged virtual memory.  If the
   DPMI host does support virtual memory, this capability is
   optional, and if present gives the client the ability to
   read and write virtual page dirty and accessed bits
   maintained by the host.
o  EXCEPTION RESTARTABILITY capability means that a faulting
   instruction inside the host kernel can always be
   restarted if the client's exception handler corrects the
   reason for the exception and returns.  Exception
   restartability allows a client to provide virtual memory
   under a DPMI host without virtual memory, or to support
   memory-mapped files under any DPMI host.
o  DEVICE MAPPING capability means that the DPMI host
   supports the optional Map Device function (Int 31H
   Function 0508H).
o  CONVENTIONAL MEMORY MAPPING capability means that the
   DPMI host supports the optional Map Conventional Memory
   function (Int 31H Function 0509H).
o  DEMAND ZERO-FILL capability means the DPMI host
   guarantees that all committed pages are initialized to
   zero when they are created.  If this capability is not
   supported, the contents of newly committed pages are
   undefined.

o    WRITE-PROTECT CLIENT capability means the DPMI host
   guarantees that the client is running at a privilege
   level such that write protection of pages is effective
   for the client's accesses and will geneate page faults.

o  WRITE-PROTECT HOST capability means the DPMI host
   guarantees that the host has configured the system such
   that write protection of pages is effective for the
   host's accesses and will generate page faults.

o  The host major and minor version numbers are OEM-specific
   and are not the DPMI version numbers.



Int 31H Function 0500H [0.9]

Get Free Memory Information

Returns information about the amount of available physical
memory, linear address space, and disk space for page
swapping.  Since DPMI clients will often run in multitasking
environments, the information returned by this function
should only be considered as advisory.  DPMI 1.0 clients
should avoid use of this function (see the last note of the
call).

Call With:

   AX     = 0500H
   ES:(E)DI= selector:offset of 48-byte buffer

Returns:

   Carry flag= clear (this function always succeeds)

   and the buffer is filled in with the following
           information:

   Offset Length  Contents
   00H    4       Largest available free block in bytes
   04H    4       Maximum unlocked page allocation in pages
   08H    4       Maximum locked page allocation in pages
   0CH    4       Linear address space size in pages
   10H    4       Total number of unlocked pages
   14H    4       Total number of free pages
   18H    4       Total number of physical pages
   1CH    4       Free linear address space in pages
   20H    4       Size of paging file/partition in pages
   24H    0CH     Reserved, all bytes set to 0FFH

Notes:

o  32-bit programs must use ES:EDI to point to the buffer.
   16-bit programs should use ES:DI.
o  Only the first field of the returned structure is
   guaranteed to contain a valid value.  Any fields that are
   not supported by the DPMI host will be set by the host to
   -1 (0FFFFFFFFH) to indicate that the information is not
   available.
o  The field at buffer offset 00H specifies the largest
   block of contiguous linear memory in bytes that could be
   allocated if the memory were to be allocated and left
   unlocked.
o  The field at buffer offset 04H specifies the largest
   number of pages that could be allocated (the value at
   offset 00H divided by the page size).
o  The field at buffer offset 08H specifies the largest
   block of memory in pages that could be allocated and then
   locked.
o  The field at buffer offset 0CH specifies the size of the
   total linear address space in pages.  This value includes
   all linear address space that has already been allocated.
o  The field at buffer offset 10H specifies the total number
   of pages that are currently un
locked and could be paged out.  This value also contains any free
   pages.
o  The field at buffer offset 14H specifies the number of
   physical pages that currently are not in use.
o  The field at offset 18H specifies the total number of
   physical pages that the DPMI host manages.  This value
   includes all free, locked, and unlocked physical pages.
o  The field at offset 20H specifies the size of the DPMI
   host's paging partition or file in pages.
o  The size of the pages used by the DPMI host can be
   obtained with the Get Page Size function (Int 31H
   Function 0604H).
o  DPMI 1.0 clients should use Int 31H Function 050BH in
   preference to this function.  This function is supported
   in DPMI 1.0 solely for backward compatibility with DPMI
   0.9.
Int 31H Function 0501H [0.9]

Allocate Memory Block

Allocates and commits a block of linear memory.

Call With:

   AX     = 0501H
   BX:CX  = size of block (bytes, must be nonzero)

Returns:

   if function successful
   Carry flag= clear
   BX:CX  = linear address of allocated memory block
   SI:DI  = memory block handle (used to resize and free
           block)

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8012H   linear memory unavailable
           8013H   physical memory unavailable
           8014H   backing store unavailable
           8016H   handle unavailable
           8021H   invalid value (BX:CX = 0)

Notes:

o  The allocated block is guaranteed to have at least
   paragraph  alignment.
o  This function always creates committed pages.
o  This function does not allocate any descriptors for the
   memory block.  It is the responsibility of the client to
   allocate and initialize any descriptors needed to access
   the memory with additional DPMI function calls.
o  Under DPMI hosts that support virtual memory, the memory
   block will be allocated unlocked.  The client can lock
   some or all of the memory after it is allocated with the
   Lock Linear Region function (Int 31H Function 0600H).
o  Under many DPMI hosts, allocations by this function are
   page granular.  This means, for example, that if the DPMI
   host uses a page size of 4 KB (1000H), an allocation of
   1001H bytes will actually result in an allocation of
   2000H bytes.  Therefore, it is best to always allocate
   memory in multiples of the unit of granularity (under
   DPMI 0.9, use 4K bytes), which can be obtained with Int
   31H Function 0604H.

Int 31H Function 0502H [0.9]

Free Memory Block

Frees a memory block that was previously allocated with
either the Allocate Memory Block function (Int 31H Function
0501H) or the Allocate Linear Memory Block function (Int 31H
Function 0504H).

Call With:

   AX     = 0502H
   SI:DI  = memory block handle

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8023H   invalid handle

Notes:

o  This call will correctly free all of the possible page
   types that can occur in a memory block: committed pages,
   uncommitted pages, and mapped pages (see Appendix A:
   Glossary).

o  No descriptors are freed by this call.  It is the
   client's responsibility to free any descriptors that it
   previously allocated to map the memory block.
   Descriptors should be freed before linear memory blocks.

Int 31H Function 0503H [0.9]

Resize Memory Block

Changes the size of a memory block that was previously
allocated with either the Allocate Memory Block function
(Int 31H Function 0501H) or the Allocate Linear Memory Block
function (Int 31H Function 0504H).

Call With:

   AX     = 0503H
   BX:CX  = new size of block (bytes, must be nonzero)
   SI:DI  = memory block handle

Returns:

   if function successful
   Carry flag= clear
   BX:CX  = new linear address of memory block
   SI:DI  = new handle for memory block

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8012H   linear memory unavailable
           8013H   physical memory unavailable
           8014H   backing store unavailable
           8016H   handle unavailable
           8021H   invalid value (BX:CX = 0)
           8023H   invalid handle (in SI:DI)

Notes:

o  After this function returns, the previous handle for the
   memory block is invalid and should not be used.
o  When increasing the size of a block, this function always
   creates committed pages.  When decreasing the block size,
   this call will correctly free all possible page types
   (committed pages, uncommitted pages, and mapped pages).
   The linear address and handle of the memory block may
   change  as a result of this call.
o  It is the client's responsibility to update any
   descriptors that map the memory block with the new linear
   address after resizing the block.
o  This function returns an error if the client attempts to
   resize a memory block to zero bytes.

Int 31H Function 0504H [1.0]

Allocate Linear Memory Block

Allocates a block of page-aligned linear address space.  The
base address of the block may be specified by the client,
and pages within the block may be committed or uncommitted.

Call With:

   AX     = 0504H
   EBX    = desired page-aligned linear address of memory
           block,
   or zero if linear address unspecified
   ECX    = size of block (bytes, must be nonzero)
   EDX    = flags
           Bit    Significance
           0      0 = create uncommitted pages
                  1 = create committed pages
           1-31   reserved, should be zero

Returns:

   if function successful
   Carry flag= clear
   EBX    = linear address of memory block
   ESI    = handle for memory block

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8001H   unsupported function (16-bit host)
           8012H   linear memory unavailable
           8013H   physical memory unavailable
           8014H   backing store unavailable
           8016H   handle unavailable
           8021H   invalid value (ECX = 0)
           8025H   invalid linear address (EBX not page
                   aligned)

Notes:

o  A DPMI 1.0 host that is 16-bit only will not support this
   function.
o  A 16-bit client of a 32-bit DPMI 1.0 host can use this
   function.
o  The allocated block is always page-aligned.  If a
   specific linear address is not requested (EBX = 0), the
   DPMI host allocates the memory block at any available
   page-aligned linear address.  If a specific linear
   address is requested (EBX nonzero), the host either
   allocates the block at the specified address or returns
   error code 8012H (linear memory unavailable).

o  Int 31H Function 0501H, which can also be used to
   allocate linear memory blocks, does not necessarily
   page-align its blocks and does not have the ability to
   create uncommitted pages or allocate a block at a
   specific linear address.
Int 31H Function 0505H [1.0]

Resize Linear Memory Block

Changes the size of a memory block that was previously
allocated with the Allocate Linear Memory Block function
(Int 31H Function 0504H).

Call With:

   AX     = 0505H
   ESI    = memory block handle
   ECX    = new block size (bytes, must be nonzero)
   EDX    = flags
           Bit    Significance
           0      0 = create uncommitted pages
                  1 = create committed pages
           1      0 = do not update segment descriptors
                  1 = segment descriptor update required
           2-31   reserved, must be zero

   and, if bit 1 of EDX is set (1):
   ES:EBX = selector:offset of a buffer containing an array
           of selectors, 1 word (16 bits) per selector
   EDI    = count of selectors in array

Returns:

   if function successful
   Carry flag= clear
   EBX    = new linear base address of memory block
   ESI    = new handle for memory block

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8001H   unsupported function (16-bit host)
           8012H   linear memory unavailable
           8013H   physical memory unavailable
           8014H   backing store unavailable
           8016H   handle unavailable
           8021H   invalid value (ECX=0)
           8023H   invalid handle (in ESI)

Notes:

o  A DPMI 1.0 host that is 16-bit only will not support this
   function.
o  A 16-bit client of a 32-bit DPMI 1.0 host can use this
function.
o  After this function returns, the previous handle for the
   memory block is invalid and should not be used.
o  If this function fails, the block's size and base address
   are always unmodified.
o  If the size of the block is increased, the new pages are
   committed or uncommitted according to the value of bit 0
   of EDX, and the block's linear base address may change.
   If the size of the block is decreased, pages at the end
   of the block are freed, and the block's base address is
   always unchanged.
o  If the block's linear base address is changed by this
   function, and the function was called with bit 1 of EDX
   set (1), the DPMI host updates the descriptors f
or each of the segments in the update list which fall within the
   memory block.  Descriptors for segments which do not fall
   within the memory block are not modified.  Expand-up
   segments fall within the memory block if the segment base
   is within the block.   Expand-down segments fall within
   the memory block if the (segment base + the limit - 1) is
   within the block.  In either case, the segment base is
   modified by the distance the block moves, and the segment
   limit is not changed. The moving of the memory block and
   the updating of descriptors is performed atomically; i.e.
   the host will not deliver any hardware interrupts to the
   client during the update.
o  Int 31H Function 0503H, which also resizes linear memory
   blocks, does not necessarily page-align blocks and cannot
   create uncommitted pages or update descriptors.
Int 31H Function 0506H [1.0]

Get Page Attributes

Returns the attributes of one or more pages within a linear
memory block previously allocated with Int 31H Function
0504H.

Call With:

   AX     = 0506H
   ESI    = memory block handle
   EBX    = base offset in memory block of page (or of first
           page, if requesting attributes for multiple
           pages)
   ECX    = number of pages
   ES:EDX = selector:offset of a buffer to receive page
           attributes, 1 word (16-bits) per page (see Note)

Returns:

   if function successful
   Carry flag= clear

   and buffer at ES:EDX filled in with page attributes (see
   Note)

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8001H   unsupported function (16-bit host)
           8023H   invalid handle (in ESI)
           8025H   invalid linear address (Specified range
                   is not within specified block)

Notes:

o  A DPMI 1.0 host that is 16-bit only will not support this
   function.
o  A 16-bit client of a 32-bit DPMI 1.0 host can use this
   function.
o  If EBX is not aligned, it will be rounded down to the
   next lower page boundary.
o  The specified buffer is filled in by the DPMI host with
   the attributes of the requested pages, 1 word (16-bits)
   per page, in the following format:

   Bits      Significance
   0-2       page type (0-7)
             Value  Meaning
             0      uncommitted page
             1      committed page
             2      mapped page
             3-7    currently unused
   3         0 = page is read-only
             1 = page is read/write
   4         0 = accessed/dirty bits not available for this
   page
             1 = accessed/dirty bits are supplied for this
   page in bits 5-6
   5         0 = page has not been accessed (if bit 4=1)
             1 = page has been accessed (if bit 4=1)
   6         0 = page has not been modified (if bit 4=1)
             1 = page has been modified (if bit 4=1)
   7-15      reserved, currently zero

o  Mapped pages can only occur in memory blocks under DPMI
   hosts that support the Device Mapping capability or the
   Conventional Memory Mapping capability.  See Int 31H
   Functions 0401H, 0508H, and 0509H.
o  The dirty and accessed bits are only supplied if the DPMI
   host supports the Page Accessed/Dirty capability.  DPMI
   hosts that support this capability are required to return
   dirty and accessed bits for all committed pages and for
   mapped pages created with the Map Conventional Memory
   call (Int 31H Function 0509H).  However, dirty and
   accessed bits may not be returned for individual mapped
   pages created with the Map Device call (Int 31H Function
   0508H) if the host is using page table entries (PTEs) to
   virtualize the device.
Int 31H Function 0507H [1.0]

Set Page Attributes

Sets the attributes of one or more pages within a linear
memory block previously allocated with Int 31H Function
0504H.  This function can be used to change a committed page
or a mapped page to an uncommitted page, change an
uncommitted page or a mapped page to a committed page, or
modify the read/write bit and optionally the accessed and
dirty bits on a committed or mapped page.

Call With:

   AX     = 0507H
   ESI    = memory block handle
   EBX    = offset within memory block of page(s) whose
           attributes are to be modified
   ECX    = number of pages
   ES:EDX = selector:offset of a buffer containing page
           attributes, 1 word (16-bits) per page (see Note)

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8001H   unsupported function (16-bit host)
           8002H   invalid state (page in wrong state for
                   request)
           8013H   physical memory unavailable
           8014H   backing store unavailable
           8021H   invalid value (illegal request in bits
                   0-2 of one or more page attribute words)
           8023H   invalid handle (in ESI)
           8025H   invalid linear address (specified range
                   is not within specified block)

   ECX    = number of pages that have been set

Notes:

o  A DPMI 1.0 host that is 16-bit only will not support this
   function.
o  A 16-bit client of a 32-bit DPMI 1.0 host can use this
   function.
o  If EBX is not aligned, it will be rounded down to the
   next lower page boundary.
o  An uncommitted page can be created from:
  a committed page, by releasing the physical memory or
   backing store allocated to the page;
  a mapped page, by marking it uncommitted; or
   an uncommitted page, by doing nothing.


o  A committed page can be created from:
  an uncommitted page or mapped page, by allocating
   physical memory or backing store (with undefined, or
   zero-filled contents) for the page; or
  a committed page, by doing nothing (page contents
   unmodified).

o  The attribute word (16-bits) specified for a page has the
    following format (bits 3-6 are only relevant if page is
   being created committed or its attributes are being
   modified, i.e. the value in bits 0-2 of the page
   attribute is 1 or 3):

   Bits      Significance
   0-2       page type (0-7)
             Value  Meaning
             0      create page uncommitted
             1      create page committed
             2      not allowed
             3      modify attributes without changing page
   type
             4-7    not allowed
   3         0 = page is read-only
             1 = page is read/write
   4         0 = don't modify accessed/dirty bits for page
             1 = set accessed/dirty bits as specified in
   bits 5-6
   5         0 = mark page as not accessed (if bit 4=1)
             1 = mark page as accessed (if bit 4=1)
   6         0 = mark page as not dirty (if bit 4=1)
             1 = mark page as dirty (if bit 4=1)
   7-15      reserved, should be zero

o  This function, and the optional Map Device and Map
   Conventional Memory functions (Int 31H Functions 0508H
   and 0509H), are the only means of changing the type of a
   page within an existing memory block.
o  The page read/write bit, and optionally the accessed and
   dirty bits, can be modified on an existing committed or
   mapped page, or on a committed page when it is initially
   created from an uncommitted page or a mapped page.
   However, the accessed and dirty bits are ignored if the
   host does not support the Page Accessed/Dirty capability.
   See Int 31H Function 0401H.

o  Visible page faults (page faults that can be serviced by
   a client-installed exception handler) can only occur for
   uncommitted pages or read-only pages (for definitions of
   transparent page fault and visible page fault, see
   Appendix A: Glossary).
Int 31H Function 0508H [Optional]  [1.0]

Map Device in Memory Block

Maps the physical addresses assigned to a device onto the
linear addresses of a memory block previously allocated with
Int 31H Function 0504H.

Call With:

   AX     = 0508H
   ESI    = memory block handle
   EBX    = offset within memory block of page(s) to be
           mapped (must be page-aligned)
   ECX    = number of pages to map
   EDX    = physical address of device (must be
           page-aligned)

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8001H   unsupported function (Device Mapping
                   Capability not supported)
           8003H   system integrity (invalid device address)
           8023H   invalid handle (in ESI)
           8025H   invalid linear address (specified range
                   is not within specified block or EBX/EDX
                   is not page-aligned)

Notes:

o  16-bit DPMI hosts will not support this function.  A
   16-bit client of a 32-bit DPMI 1.0 host can use this
   function.
o  Support of this call by 32-bit DPMI hosts is optional.
   Application programs or DOS Extenders which require this
   call in order to run are not DPMI Compliant.
o  Any committed or mapped pages resided in the linear
   address range that is being mapped into will be
   uncommitted or unmapped automatically by the host.
o  All pages created by this call have the mapped bit (bit
   2) set in the attributes returned by the Get Page
   Attributes function (Int 31H Function 0506H).
o  This functio
n differs from the Create Physical Address Mapping function (Int 31H
   Function 0800H) in that this function supports mapping of
   physical devices within an existing memory block, rather
   than at an arbitrary linear address.  Use of an existing
   memory block gives 32-bit programs the ability to access
   physical devices with NEAR pointers, which is often
   highly desirable for performance reasons.
o  Unlike Int 31H Function 0800H, this function allows
   mapping of  addresses below 1 MB that do not lie within
   RAM available for use by programs; e.g. this function can
    be used to map the refresh buffers of IBM-compatible
   display adapters.
o  If the DPMI host is not virtualizing the device,  it must
   disable any memory caching on the mapped pages;  in
   particular, on the 486 or later, the PCD (page cache
   disable) bit must be set in the page table entries.
o  DPMI hosts that do not virtualize physical devices can
   support this function by creating page table entries that
   map the physical device.  The page table entries must be
   marked as mapped so that the host knows not to attempt
   freeing of physical memory for the pages when the memory
   block is freed.
o  DPMI hosts are allowed to support this function for some
   physical devices and not for others, because mapping of
   virtualized devices requires page aliasing in the host -
   a complex task.  DPMI hosts with partial support for this
   function may fail the function call on virtualized
   devices (such as displays), and allow the call on
   non-virtualized devices (such as the Weitek
   coprocessors).  Allowing the client to map  a physical
   device so that it can be accessed with NEAR references,
   for example, may help the client achieve considerably
   better performance.
Int 31H Function 0509H [Optional]  [1.0]

Map Conventional Memory in Memory Block

Aliases linear  addresses below the 1 MB boundary onto the
linear addresses of a memory block previously allocated with
Int 31H Function  0504H.

Call With:

   AX     = 0509H
   ESI    = memory block handle
   EBX    = offset within memory block of page(s) to be
           mapped (must be page-aligned)
   ECX    = number of pages to map
   EDX    = linear address of conventional memory (must be
           page-aligned)

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8001H   unsupported function (Conventional Memory
                   Mapping Capability not supported)
           8003H   system integrity (invalid conventional
                   memory address)
           8023H   invalid handle (in ESI)
           8025H   invalid linear address (specified range
                   is not within specified block, or EBX/EDX
                   is not page aligned)

Notes:

o  16-bit DPMI hosts will not support this function.  A
   16-bit client of a 32-bit DPMI 1.0 host can use this
   function.
o  Support of this call by 32-bit DPMI hosts is optional.
   Application programs or DOS Extenders which require this
   call in order to run are not DPMI Compliant.
o  Any committed or mapped pages resided in the linear
   address range that is being mapped into will be
   uncommitted or unmapped automatically by the host.
o  A client may only map conventional memory that it already
   owns; i.e. memory which the client previously allocated
   with Int 31H Function 0100H or by calling DOS's Int 21H
   Function 48H directly via the translation services.
o  All pages created by this call have the mapped bit (bit
   2) set in the attributes returned by the Get Page
   Attributes function (Int 31H Function 0506H).
o  DPMI hosts that do not implement virtual memory can
   support this function by simply copying page table
   entries.  The entries must be marked as mapped so that
   the host knows not to free up those physical pages when
   the memory block is freed.
o  DPMI hosts that provide virtual memory must implement
   some form of page aliasing in order to support this
   function.
o  The function can provide a large contiguous memory space
   without virtual memory support.

  Implementors of DPMI hosts which do not provide virtual
   memory are encouraged to support this function.  Without
   this function, conventional memory may be inaccessible to
   a 32-bit nonsegmented client, because the client may need
   contiguous linear memory for its code and data.  32-bit
   clients can always guarantee that conventional memory is
   not wasted with the following strategy:

  Call DOS to allocate any free conventional memory
  If the DPMI host supports virtual memory, call the Mark
   Real Mode Region Pageable function (Int 31H Function
   0602H) to ensure that the host has not locked down
   conventional memory.
  If the host does not support virtual memory but supports
   the Map Conventional Memory function (Int 31H Function
   0509H), allocate a memory block with uncommitted pages,
   then use Function 0509H to make the physical memory
   allocated below 640 KB addressable in the memory block,
   and therefore useable by the 32-bit application program.
Int 31H Function 050AH [1.0]

Get Memory Block Size and Base

Returns the size of a memory block that was previously
allocated with Int 31H Function 0501H or 0504H.

Call With:

   AX     = 050AH
   SI:DI  = memory block handle

Returns:

   if function successful
   Carry flag= clear
   SI:DI  = size of memory block (bytes)

   BX:CX  = base address of memory block if function
           unsuccessful
   Carry flag= set
   AX     = error code
           8023H   invalid handle
Int 31H Function 050BH [1.0]

Get Memory Information

Returns information about available physical and virtual
memory.  Since DPMI clients will often run in multitasking
environments, some of information related to shared
resources returned by this function should only be
considered as advisory.

Call With:

   AX     = 050BH
   ES:(E)DI= selector:offset of 128-byte buffer

Returns:

   if function successful
   Carry flag= clear (this function always succeeds in DPMI
           1.0)

   and the buffer pointed to by ES:(E)DI is filled in with
           the following information:

   Offset Length  Contents
   00H    4       Total allocated bytes of physical memory
   controlled by DPMI host
   04H    4       Total allocated bytes of virtual memory
   controlled by DPMI host
   08H    4       Total available bytes of virtual memory
   controlled by DPMI host
   0CH    4       Total allocated bytes of virtual memory
   for this virtual machine
   10H    4       Total available bytes of virtual memory
   for this virtual machine
   14H    4       Total allocated bytes of virtual memory
   for this client
   18H    4       Total available bytes of virtual memory
   for this client
   1CH    4       Total locked bytes of memory for this
   client
   20H    4       Maximum locked bytes of memory for this
   client
   24H    4       Highest linear address available to this
   client
   28H    4       Size in bytes of largest available free
   memory block
   2CH    4       Size of minimum allocation unit in bytes
   30H    4       Size of the allocation alignment unit in
   bytes
   34H    4CH     Reserved, currently zero

   if function unsuccessful
   Carry flag= set (this function always fails in DPMI 0.9)

Notes:

o  DPMI 1.0 clients should use this function in preference
   to Int 31H Function 0500H.
o  The "total available bytes" field of the data structure
   pointed by ES:(E)DI means the total bytes minus all of
   the allocated bytes.
Int 31H Function 0600H [0.9]

Lock Linear Region

Locks the specified linear address range.

Call With:

   AX     = 0600H
   BX:CX  = starting linear address of memory to lock
   SI:DI  = size of region to lock (bytes)

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8013H   physical memory unavailable
           8017H   lock count exceeded
           8025H   invalid linear address (unallocated
                   pages)

Notes:

o  If the function returns an error, none of the memory has
   been locked.
o  If the specified region overlaps part of a page at the
   beginning or end of the region, the page(s) will be
   locked.
o  This function may be called more than once for a given
   page; the DPMI host maintains a lock count for each page.
o  This function is ignored by DPMI implementations that do
   not support virtual memory; the function will return the
   Carry flag clear to indicate success, but has no other
   effect.  DPMI hosts which support virtual memory may also
   choose to ignore this function, but such hosts must be
   able to handle page faults transparently at arbitrary
   points during a client's execution, including within
   interrupt and exception handlers.
Int 31H Function 0601H [0.9]

Unlock Linear Region

Unlocks a linear address range that was previously locked
using the Lock Linear Region function (Int 31H Function
0600H).

Call With:

   AX     = 0601H
   BX:CX  = starting linear address of memory to unlock
   SI:DI  = size of region to unlock (bytes)

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8002H   invalid state (page not locked)
           8025H   invalid linear address (unallocated
                   pages)

Notes:

o  If the function returns an error, none of the memory has
   been unlocked.
o  If the specified region overlaps part of a page at the
   beginning or end of the region, the page(s) will be
   unlocked.
o  A lock count is maintained for each locked page; the page
   is not unlocked until the lock count is decremented to
   zero (i.e. the number of Lock Region Int 31H Function
   0600H calls has been balanced by the same number of
   Unlock Region Int 31H Function 0601H calls).
o  This function is ignored by DPMI implementations that do
   not support virtual memory; the function will return the
   Carry flag clear to indicate success, but has no other
   effect.  DPMI hosts which support virtual memory may also
   choose to ignore this function, but such hosts must be
   able to handle page faults transparently at arbitrary
   points during a client's execution, including within
   interrupt and exception handlers.
Int 31H Function 0602H [0.9]

Mark Real Mode Region as Pageable

Advises the DPMI host that the specified memory below the 1
MB boundary may be paged to disk.

Call With:

   AX     = 0602H
   BX:CX  = starting linear address of memory to mark as
           pageable
   SI:DI  = size of region to be marked (bytes)

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8002H   invalid state (region already marked as
                   pageable)
           8025H   invalid linear address (region is above 1
                   MB boundary)

Notes:

o  If the function returns an error, none of the memory has
   been marked as pageable.
o  If the specified region overlaps part of a page at the
   beginning or end of the region, the page(s) will not be
   marked as pageable.
o  Pageability information for a real mode region is
   maintained as a binary state, not a count.  Therefore,
   multiple calls to this function for the same region have
   no effect.
o  For compatibility with DPMI version 0.9 hosts, a client
   must call the Relock Real Mode Region function (Int 31H
   Function 0603H) to relock the memory region before
   terminating.  Memory that remains unlocked after the
   client has terminated could result in fatal page faults
   when another program is executed in the same address
   space.  DPMI 1.0 hosts automatically relock real mode
   memory at client termination.
o  Under some DPMI hosts, all conventional memory may be
   locked by default.  If a protected mode program is using
   memory in the first megabyte of address space, it is
   recommended that this function be used to turn off
   automatic page locking for regions of memory that will
   not be touched at interrupt time.
o  The client must not mark memory as pageable in regions
   that it does not own; i.e. it may only mark as pageable
   memory that it has previously allocated with Int 31H
   Function 0100H or by a direct call to DOS via the
   translation functions.  For example, marking all free DOS
   memory as pageable under some DPMI hosts could cause a
   page fault to occur while inside of DOS, resulting in a
   crash.  Also, a client should not mark the DPMI host data
   area as pageable.
o  Note that address space marked as pageable by this
   function can still be locked using the Lock Linear Region
    function (Int 31H Function 0600H).  This function is
   just an advisory service to allow memory that does not
   need to be locked to be paged out; it disables any
   automatic locking of real mode memory performed by the
   DPMI host.
o  This function is ignored by DPMI implementations that do
   not support virtual memory; the function will return the
   Carry flag clear to indicate success, but has no other
   effect.  DPMI hosts which support virtual memory may also
   choose to ignore this function, but such hosts must be
   able to handle page faults transparently at arbitrary
   points during a client's execution, including within
   interrupt and exception handlers.
Int 31H Function 0603H [0.9]

Relock Real Mode Region

Relocks a memory region that was previously declared as
pageable with the Mark Real Mode Region as Pageable function
(Int 31H Function 0602H).

Call With:

   AX     = 0603H
   BX:CX  = starting linear address of memory to relock
   SI:DI  = size of region to relock (bytes)

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8002H   invalid state (region not marked as
                   pageable)
           8013H   physical memory unavailable
           8025H   invalid linear address (region is above 1
                   MB boundary)

Notes:

o  If the function returns an error, none of the memory has
   been relocked.
o  If the specified region overlaps part of a page at the
   beginning or end of the region, the page(s) will not be
   relocked.
o  This function is ignored by DPMI implementations that do
   not support virtual memory; the function will return the
   Carry flag clear to indicate success, but has no other
   effect.  DPMI hosts which support virtual memory may also
   choose to ignore this function, but such hosts must be
   able to handle page faults transparently at arbitrary
   points during a client's execution, including within
   interrupt and exception handlers.
o  If Function 0602H is implemented as a "no-operation" on a
   particular DPMI host, this function will likewise do
   nothing.  In other words, this function should not be
   used to lock memory, but only to restore the default
   state of the host's conventional memory locking.
Int 31H Function 0604H [0.9]

Get Page Size

Returns the size of a single memory page in bytes.

Call With:

   AX     = 0604H

Returns:

   if function successful
   Carry flag= clear
   BX:CX  = page size in bytes

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8001H   unsupported function (16-bit host)
Int 31H Function 0700H [0.9]

Reserved

Function 0700H is reserved for historical reasons and should
not be called.
Int 31H Function 0701H [0.9]

Reserved

Function 0701H  is reserved for historical reasons and
should not be called.
Int 31H Function 0702H [0.9]

Mark Page as Demand Paging Candidate

Notifies the DPMI host that a range of pages may be placed
at the head of the page-out candidate list, forcing these
pages to be replaced ahead of other pages even if the memory
has been accessed recently.  The contents of the pages will
be preserved.

Call With:

   AX     = 0702H
   BX:CX  = starting linear address of pages to mark as
           paging candidates
   SI:DI  = size of region to mark (bytes)

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8025H   invalid linear address (range
                   unallocated)

Notes:

o  This function does not force the pages to be swapped to
   disk immediately and should be treated as advisory only.
o  This function will always succeed on hosts that do not
   implement demand-paged virtual memory.
o  Partial pages will not be marked.
o  This function is useful, for example, if a client knows
   that a given piece of data will not be accessed for a
   long period of time.  That data is ideal for swapping to
   disk so that the physical memory it occupies can be used
   for other purposes.
Int 31H Function 0703H [0.9]

Discard Page Contents

Discards the entire contents of a given linear memory range.
This function is used when a memory object (such as a data
structure) that occupies a given area of memory is no longer
needed, so that the area will not be paged to disk
unnecessarily.  The contents of the discarded region will be
undefined.

Call With:

   AX     = 0703h
   BX:CX  = starting linear address of pages to discard
   SI:DI  = size of region to discard (bytes)

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8025H   invalid linear address (range
                   unallocated)

Notes:

o  Partial pages and locked pages will not be discarded.
Int 31H Function 0800H [0.9]

Physical Address Mapping

Converts a physical address into a linear address.
  This function allows device drivers running under DPMI
hosts which use paging to reach physical memory that is
associated with their devices above the 1 MB boundary
Examples of such devices are the Weitek numeric coprocessor
(usually mapped at 3 GB), buffers that hold scanner bit
maps, and high-end displays that can be configured to make
display memory appear in extended memory.

Call With:

   AX     = 0800H
   BX:CX  = physical address of memory
   SI:DI  = size of region to map (bytes)

Returns:

   if function successful
   Carry flag= clear
   BX:CX  = linear address that can be used to access the
           physical memory

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8003H   system integrity (DPMI host memory
                   region)
           8021H   invalid value (address is below 1 MB
                   boundary)

Notes:

o  It is the caller's responsibility to allocate and
   initialize a descriptor for access to the memory.
o  This function should only be used by clients that
   absolutely require direct access to a memory mapped
   device at physical addresses above 1 MB.  Clients should
   not use this function to access memory below the 1 MB
   boundary (the real mode addressable region).  See also
   Int 31H Functions 0002H, 0508H, and 0509H.
o  When this function is called, the DPMI host either
   creates page table entries that directly map the physical
   addresses requested and returns the linear address of the
   created page table entries, or else just returns the
   linear address of the memory region that is already used
   to map the requested device.  For example, if the client
   attempts to map a Weitek coprocessor and the host already
   has a linear region set up to map the Weitek chip and
   virtualize it, it would simply return the linear address
   of the existing region.  If the host does not virtualize
   the Weitek chip, it would create 16 page table entries
   that map the 64 KB Weitek address space and return a
   linear address corresponding to the new page table
   entries.
o  If the host is not virtualizing the device, it must
   disable any memory caching on the mapped pages;  in
   particular, on the 80486 the host must set the PCD (page
   cache disable) bit in the page table entries.
o  The host is permitted to fail any memory mapping call.
   However, the host should support this function whenever
   possible, to achieve compatibility with application
   programs that use memory-mapped devices of which the host
   is not aware.  Useful guidelines are that the host should
   fail any attempt to map addresses below 1 MB, or
   addresses which the host considers to be general-purpose
   RAM memory.  Attempts to map any other physical address
   should succeed, since the host should either (a) already
   know about the device and be able to return a linear
   address used to access the device, or (b) assume the
   program is attempting to map a legitimate device of which
   the host has no knowledge.

o  Programs and device drivers which need to perform DMA I/O
   to physical addresses in a virtualized hardware
   environment should use the Virtual DMA Services (see the
   Glossary entry for the Virtual DMA Services
   Specification).   Also see page 10 of the DPMI execution
   environment section.
Int 31H Function 0801H [1.0]

Free Physical Address Mapping

Releases a mapping of physical to linear addresses that was
previously obtained with the Physical Address Mapping
function (Int 31H Function 0800H).

Call With:

   AX     = 0801H
   BX:CX  = linear address returned by physical address
           mapping call

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8025H   invalid linear address

Notes:

o  The client should call this function when it is finished
   using a device previously mapped to linear addresses with
   the Physical Address Mapping function (Int 31H Function
   0800H).
Int 31H Function 0900H [0.9]

Get and Disable Virtual Interrupt State

Disables the virtual interrupt flag and returns the previous
state of the virtual interrupt flag.

Call With:

   AX     = 0900H

Returns:

   Virtual interrupts disabled
   Carry flag= clear (this function always succeeds)
   AL     = 0 if virtual interrupts were previously disabled
          = 1 if virtual interrupts were previously enabled

Notes:

o  AH is not changed by this function.  Therefore, the
   previous state can be restored by simply executing
   another Int 31H.  See Int 31H Function 0901H.

o  A client that does not need to know the prior interrupt
   state can execute the CLI instruction rather than calling
   this function.  The instruction may be trapped by the
   host and should be assumed to  be very slow.
Int 31H Function 0901H [0.9]


Get and Enable Virtual Interrupt State

Enables the virtual interrupt flag and returns the previous
state of the virtual interrupt flag.

Call With:

   AX     = 0901H

Returns:

   Virtual interrupts enabled
   Carry flag= clear (this function always succeeds)
   AL     = 0 if virtual interrupts were previously disabled
          = 1 if virtual interrupts were previously enabled

Notes:

o  AH is not changed by this function.  Therefore, the
   previous state can be restored by simply executing
   another Int 31H.  See Int 31H Function 0900H.

o  A client that does not need to know the prior interrupt
   state can execute the STI instruction rather than calling
   this function.  The instruction may be trapped by the
   host and should be assumed to  be very slow.

Int 31H Function 0902H [0.9]

Get Virtual Interrupt State

Returns the current state of the virtual interrupt flag.

Call With:

   AX     = 0902H

Returns:

   Carry flag= clear (this function always succeeds)
   AL     = 0 if virtual interrupts are disabled
          = 1 if virtual interrupts are enabled

Notes:

o  This function should be used in preference to the PUSHF
   instruction to examine the interrupt flag, because the
   PUSHF instruction returns the physical interrupt flag
   rather than the virtualized (per-client) interrupt flag.
   On some DPMI hosts, the physical interrupt flag will
   always be enabled, even when hardware interrupts are not
   being passed through to the client.
Int 31H Function 0A00H [0.9]

Get Vendor-Specific API Entry Point

Returns an address which can be called to use host-specific
extensions to the standard set of DPMI functions.  DPMI 1.0
clients should avoid use of this function (see Note).

Call With:

   AX     = 0A00H
   DS:(E)SI= selector:offset of ASCIIZ (null-terminated)
           string which identifies the DPMI host vendor

Returns:

   if function successful
   Carry flag= clear
   ES:(E)DI= selector:offset of extended API entry point

   and DS, FS, GS, EAX, EBX, ECX, EDX, ESI, and EBP may be
           modified.
   if function unsuccessful
   Carry flag= set
   AX     = error code
           8001H   unsupported function (extension not
                   found)

Notes:

o  The null-terminated string specifies the host-specific
   vendor name or some other unique identifier to obtain a
   specific extension entry point.  The string comparison
   used to look up the API entry point is case-sensitive.
o  Clients must use a FAR CALL to reach the extended API
   entry point.
o  All extended API parameters are specified by the vendor.
o  DPMI 1.0 clients should use Int 2FH Function 168AH in
   preference to this function.  DPMI 1.0 hosts support this
   function solely for backward compatibility with DPMI 0.9
   clients.
Int 31H Function 0B00H [0.9]

Set Debug Watchpoint

Sets a debug watchpoint at the specified linear address.

Call With:

   AX     = 0B00H
   BX:CX  = linear address of watchpoint
   DL     = size of watchpoint (1, 2, or 4 bytes)
   DH     = type of watchpoint
           0 = execute
           1 = write
           2 = read/write

Returns:

   if function successful
   Carry flag= clear
   BX     = watchpoint handle

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8016H   too many breakpoints
           8021H   invalid value (in DL or DH)
           8025H   invalid linear address (linear address
                   not mapped or alignment error)

Notes:

o  Under DPMI 1.0, the handle will be in the range 0-14.
   Under DPMI 0.9, the handle range is not limited.
o  The watchpoint handle corresponds to the bit number in
   the Virtual DR6 returned in the exception frame (see Int
   31H Function 0212H and page 18).

Int 31H Function 0B01H [0.9]

Clear Debug Watchpoint

Clears a debug watchpoint that was previously set using the
Set Debug Watchpoint function (Int 31H Function 0B00H), and
releases the watchpoint
handle.

Call With:

   AX     = 0B01H
   BX     = watchpoint handle

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8023H   invalid handle


Int 31H Function 0B02H [0.9]

Get State of Debug Watchpoint

Returns the state of a debug watchpoint that was previously
set using the Set Debug Watchpoint function (Int 31H
Function 0B00H).

Call With:

   AX     = 0B02H
   BX     = watchpoint handle

Returns:

   if function successful
   Carry flag= clear
   AX     = watchpoint status
           Bit    Significance
           0      0 = watchpoint has not been encountered
                  1 = watchpoint has been encountered
           1-15   reserved

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8023H   invalid handle

Notes:

o  The client can use Int 31H Function 0B03H to clear the
   watchpoint state without releasing the watchpoint handle.
Int 31H Function 0B03H [0.9]

Reset Debug Watchpoint

Resets the state of a previously defined debug watchpoint;
i.e. a subsequent call to Int 31H Function 0B02H will
indicate that the debug watchpoint has not been encountered.

Call With:

   AX     = 0B03H
   BX     = watchpoint handle

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8023H   invalid handle


Int 31H Function 0C00H [1.0]

Install Resident Service Provider Callback

Protected mode resident service providers (protected mode
TSRs) can provide services to 16-bit DPMI programs, 32-bit
DPMI programs, or both.  A resident service provider uses
this function to request notification from the host whenever
another DPMI program in the same virtual machine is loaded
or terminated.

Call With:

   AX     = 0C00H
   ES:(E)DI= selector:offset of 40-byte buffer with the
           following structure:

           OffsetLengthContents
           00H    8Descriptor for 16-bit data segment
           08H    8Descriptor for 16-bit code segment
           10H    2Offset of 16-bit callback procedure
           12H    2Reserved
           14H    8Descriptor for 32-bit data segment
           1CH    8Descriptor for 32-bit code segment
           24H    4Offset of 32-bit callback procedure

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8021H   invalid value (access rights/type bytes
                   invalid, or offset outside segment
                   limits)
           8025H   invalid linear address (descriptor
                   references a linear address range outside
                   that allowed for DPMI clients)
           8015H   callback unavailable (host unable to
                   allocate resources for resident handler
                   initialization callback)

Notes:

o  A DPMI client that uses this function declares its intent
   to provide resident protected mode services.  The client
   must subsequently terminate and stay resident using Int
   31H Function 0C01H.  DPMI clients which intend to stay
   resident only to provide services to real mode programs
   should not use this function.
o  The data structure provides room for a data descriptor, a
   code descriptor, and an offset for both 16-bit and 32-bit
   protected modes.  The client can conveniently initialize
   the descriptor fields to valid values by fetching copies
   of  its current code and data descriptors with Int 31H
   Function 000BH.
o  If only one mode is supported by the resident service
   provider, then the code descriptor for the unsupported
   mode should be initialized to zero.
o  This function is called on the locked protected mode
   stack.

o  For further details on programming of resident service
   providers, see page 41.
Int 31H Function 0C01H [1.0]

Terminate and Stay Resident

A resident service provider uses this function after its
initialization to terminate execution while leaving its
protected mode memory (and optionally some real mode memory)
allocated.

Call With:

   AX     = 0C01H
   BL     = return code
   DX     = number of paragraphs (16-byte blocks) of DOS
           memory to reserve

Returns:

   Nothing (this call never returns)

Notes:

o  This function should only be used by DPMI clients which
   only provide resident services to other DPMI protected
   mode clients.  If the objective is only to provide
   resident services to real mode programs, the client
   should use the DPMI translation service Int 31H Function
   0300H to invoke DOS's Int 21H Function 31H directly.
o  The value in DX only specifies the size of DOS allocated
   memory to reserve.  Any protected mode memory owned by
   the program remains allocated unless it is explicitly
   released before executing this function.  Note that the
   value in DX must either be 0 or a minimum of 6.  If DX is
   0, the DPMI host executes a DOS real mode terminate
   function (Int 21H Function 4CH), and no real mode memory
   is reserved.  If DX is nonzero, the DPMI host requests
   the DOS real mode terminate-and-stay-resident function
   (Int 21H Function 31H).

o  If the client has not made a prior call to Int 31H
   Function 0C00H, the client will simply be terminated.
o  For further details on programming of resident service
   providers, see page 41.
Int 31H Function 0D00H [1.0]

Allocate Shared Memory

Allocates a memory block that may be shared by DPMI clients.

Call With:

   AX     = 0D00H
   ES:(E)DI= selector:offset of shared memory allocation
           request structure in the following format:

           Offset   Length  Contents
           00H      4       Requested length of shared
                            memory block (set by client, may
                            be zero)
           04H      4       Length actually allocated (set
           by host)
           08H      4       Shared memory handle (set by
           host)
           0CH      4       Linear address of shared memory
                            block (set by host)
           10H      6       offset32:selector of ASCIIZ
                            (null-terminated ASCII) name for
                            shared memory block (set by
                            client)
           16H      2       Reserved
           18H      4       Reserved, must be zero

Returns:

   if function successful
   Carry flag= clear

   and the request structure fields at offsets 04H, 08H, and
           0CH updated  by host
   if function unsuccessful
   Carry flag= set
   AX     = error code
           8012H   linear memory unavailable
           8013H   physical memory unavailable
           8014H   backing store unavailable
           8016H   handle unavailable
           8021H   invalid value (name for the memory block
                   is too long)

   and the request structure fields at offsets 04H, 08H and
                   0CH unmodified by host

Notes:

o  For 16-bit programs, the high word of the offset32 for
   the ASCIIZ name must be zero.
o  The maximum length of the shared memory block name is 128
   characters, including the terminal null character.
o  The linear address provided by the host is guaranteed to
   be the same for all clients in all virtual machines using
   a shared memory block.  The client must establish
   addressability for the block by allocating and
   initializing a descriptor with separate function calls.
o  No assumptions should be made about handle values.
   Successive allocations of the same shared memory block by
    the same client may return distinct handles; the client
   is responsible for tracking and individually deallocating
   each handle.
o  The first client that allocates a shared memory block
   determines its size; the length requested and the length
   actually allocated will always be equal, if the
   allocation succeeds at all.  Subsequent allocations by
   the same or different clients that specify the same or a
   different size will succeed, but the size of the block
   will remain unchanged.  The actual size of the block is
   always returned to the client at offset 4 in the shared
   memory allocation request structure.
o  Allocation of zero-length shared memory blocks is
   explicitly allowed.  The handle of a zero-length block
   can be used with the serialization functions (Int 31H
   Functions 0D02H and 0D03H) as a semaphore for
   inter-client communication.  The linear address that is
   returned at offset 0CH in the data structure for
   zero-length blocks is undefined, and any reference to it
   may produce a page fault.
o  The first paragraph (16 bytes) of the shared memory block
   (or the entire shared block, if smaller than 16 bytes)
   will always be initialized to zero on the first
   allocation and can be used by clients as an "area
   initialized" indicator.  For example, a shared memory
   block might be used by a suite of cooperating client
   programs to hold a table of static data or a subroutine
   library.  The first client to allocate the shared memory
   block can obtain exclusive ownership of the block with
   Int 31H Function 0D02H, load the necessary data or code
   into the block from disk, set the first 16 bytes of the
   block to a nonzero value, and finally release its
   ownership
of the block with Int 31H Function 0D03H.  Other clients that allocate
   the shared memory block can check the "area initialized"
   indicator and know that the desired code or data is
   already present in memory.
o  Shared memory block allocations and serializations are
   tracked by the host on a per client basis. All shared
   memory allocations for a client are freed by the host
   when the client terminates.

Int 31H Function 0D01H [1.0]

Free Shared Memory

Deallocates a shared memory block.

Call With:

   AX     = 0D01H
   SI:DI  = handle of shared memory block to free

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8023H   invalid handle

Notes:

o  The shared memory handle becomes invalid after the shared
   memory block is deallocated, and should not be used in
   any other function call (such as serialization).
o  The host maintains virtual machine use counts and a
   global use count for each shared memory block.  A
   virtual machine use count is the number of allocation
   calls (Int 31H Function 0D00H) that have been issued by a
   particular virtual machine for the shared block, while
   the global use count corresponds to the number of virtual
   machines which have access to the block.  When a virtual
   machine use count reaches zero, the clients in that
   virtual machine no longer have addressability to the
   shared memory block; when the global use count reaches
   zero, the shared memory block is destroyed by the host.
o  It is the client's responsibility to free any descriptors
   that it has allocated to map the shared memory block.
o  Applications should not depend on this function to
   release a previous successful serialization for the same
   shared memory block.  Serialization is only released by
   this function when the virtual machine use count goes to
   0 (i.e., the client no longer has access to the shared
   memory block).
Int 31H Function 0D02H [1.0]

Serialize on Shared Memory

Requests serialization of a shared memory block.  Successful
serialization symbolizes ownership or right of access to a
block, and can be used by DPMI clients to synchronize the
inspection or modification of a shared memory block.

Call With:

   AX     = 0D02H
   SI:DI  = shared memory block handle
   DX     = option flags
           Bit    Significance
           0      0 = suspend client until serialization
           available
                  1 = return immediately with error if
           serialization not available
           1      0 = exclusive serialization requested
                  1 = shared serialization requested
           2-15   reserved, must be zero

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8004H   deadlock (host detected a deadlock
                   situation)
           8005H   request cancelled with Int 31H Function
                   0D03H
           8017H   lock count exceeded
           8018H   exclusive serialization already owned by
                   another client
           8019H   shared serialization already owned by
                   another client
           8023H   invalid handle

Notes:

o  For each client, the DPMI host maintains four different
   local (virtual machine) serialization counts (exclusive,
   shared, pending shared, and pending exclusive) for each
   shared memory block, as well as a global serialization
   count.  The global serialization count is only updated
   when the sum of a virtual machine's exclusive and shared
   serialization counts goes from 0 to 1 (serialize) or 1 to
   0 (free).
o  A successful exclusive serialization blocks any
   serialization request (exclusive or shared) for the same
   block by another virtual machine.   Exclusive
   serialization should be regarded as "ownership for
   writing," and should only be requested if the client
   intends to modify the block.  A successful shared
   serialization will only block requests for exclusive
   serialization by another client.  Shared serialization
   can be thought of as "read-only access," and should used
   when the client only intends to inspect the block and
   will not change its contents.
o  Setting bit 0 of DX to 1 when the serialization request
   is made allows a client to determine whether a shared
   memory area is serialized without being suspended.
   Clients which "poll" for the availability of a resource
   in this manner are encouraged to yield the CPU with Int
   2FH Function 1680H at appropriate intervals.
o  A serialization call that causes a client to be suspended
   can be canceled by a client interrupt service routine
   (such as a keyboard or timer interrupt handler)
   requesting the Free Serialization function (Int 31H
   Function 0D03H).  In such cases, the original
   serialization request will return with the Carry flag set
   and AX = 8005H.
o  A client that has been suspended while waiting for
   serialization of a shared memory block can still service
   interrupts.  Some hosts may need to reissue the
   serialization request on behalf of the client after the
   interrupt service routine returns, but this event will be
   invisible to the client.
o  Hosts are not required to detect deadlock.  Clients that
   terminate and stay resident in order to function as
   resident service providers, executing in the context of
   other clients, must be careful to avoid deadlocks and
   incorrect sequencing in acquiring and releasing
   resources.
Int 31H Function 0D03H [1.0]

Free Serialization on Shared Memory

Releases a shared memory block serialization that was
previously obtained with Int 31H Function 0D02H.

Call With:

   AX     = 0D03H
   SI:DI  = shared memory block handle
   DX     = option flags
           Bit    Significance
           0      0 = release exclusive serialization
                  1 = release shared serialization
           1      0 = don't free pending serialization
                  1 = free pending serialization (see Note)
           2-15   reserved, must be zero

Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8002H   invalid state (client does not own a
                   successful serialization of the specified
                   type)
           8023H   invalid handle

Notes:

o  For each client, the DPMI host maintains four different
   local (virtual machine) serialization counts (exclusive,
   shared, pending shared, and pending exclusive) for each
   shared memory block, as well as a global serialization
   count.  The global serialization count is only updated
   when the sum of a virtual machine's exclusive and shared
   serialization counts goes from 0 to 1 (serialize) or 1 to
   0 (free).
o  A client's interrupt handler can call this function with
   bit 1 of DX set to cancel a serialization request that
   has suspended the main thread of execution of the same
   client.  In such cases, the original serialization
   request will return with the Carry flag set and AX =
   8005H.
Int 31H Function 0E00H [1.0]

Get Coprocessor Status

Returns information about whether or not a numeric
coprocessor exists, the type of coprocessor available (if
any), and whether or not the host or client is providing
coprocessor emulation.

Call With:

   AX     = 0E00H

Returns:

   if function successful
   Carry flag= clear (this function always succeeds in DPMI
           1.0)
   AX     = coprocessor status

           Bit    Significance
           0      MPv (MP bit in the virtual MSW/CR0)
                  0 = numeric coprocessor is disabled for
           this client
                  1 = numeric coprocessor is enabled for
           this client
           1      EMv (EM bit in the virtual MSW/CR0)
                  0 = client is not emulating coprocessor
           instructions
                  1 = client is emulating coprocessor
           instructions
           2      MPr (MP bit from the actual MSW/CR0)
                  0 = numeric coprocessor is not present
                  1 = numeric coprocessor is present
           3      EMr (EM bit from the actual MSW/CR0)
                  0 = host is not emulating coprocessor
           instructions
                  1 = host is emulating coprocessor
           instructions
           4-7    coprocessor type
                  00H = no coprocessor
                  02H = 80287
                  03H = 80387
                  04H = 80486 with numeric coprocessor
                          05H-0FH  reserved for future
           numeric processors
           8-15   not applicable


   if function unsuccessful
   Carry flag= set (this function always fails in DPMI 0.9)

Notes:

o  If the real EM (EMr) bit is set, the host is supplying or
   is capable of supplying floating point emulation.
o  If the MPv bit is not set, the host may not need to save
   the coprocessor state for this virtual machine to improve
   system performance.
o  MPr bit setting should be consistent with the setting of
   coprocessor type information. Ignore MPr bit information
   if it is in conflict with the coprocessor type
   information.
o  If the virtual EM (EMv) bit i
s set, the host delivers all coprocessor exceptions to the client, and
   the client is performing its own floating point emulation
   (whether or not a coprocessor is present or the host also
   has a floating point emulator).  In other words, if the
   EMv bit is set, the host sets the EM bit in the real CR0
   while the virtual machine is active, and reflects
   coprocessor not present faults (Int 7) to the virtual
   machine.
o  A client can determine the CPU type with Int 31H Function
   0400H, but a client should not draw any conclusions about
   the presence or absence of a coprocessor based on the CPU
   type alone.
Int 31H Function 0E01H [1.0]

Set Coprocessor Emulation

Enables or disables the numeric coprocessor for this virtual
machine  and the reflection of coprocessor exceptions to the
client.

Call With:

   AX     = 0E01H
   BX     = coprocessor bits

           Bit    Significance
           0      new value of MPv bit for client's virtual
           CR0
                  0 = disable numeric coprocessor for this
           client
                  1 = enable numeric coprocessor for this
           client
           1      new value of EMv bit for client's virtual
           CR0
                  0 = client will not supply coprocessor
           emulation
                  1 = client will supply coprocessor
           emulation
           2-15   not applicable


Returns:

   if function successful
   Carry flag= clear

   if function unsuccessful
   Carry flag= set
   AX     = error code
           8026H   invalid request (client requested
                   disabling coprocessor on a processor
                   which does not support this)

Notes:

o  If the MPv bit is not set, the host may not need to save
   the coprocessor state for this virtual machine to improve
   system performance.
o  If the virtual EM (EMv) bit is set, the host delivers all
   coprocessor exceptions to the client, so that the client
   can provide its own floating point emulation (whether or
   not a coprocessor is present or the host also has a
   floating point emulator).  In other words, if the EMv bit
   is set, the host sets the EM bit in the real CR0 while
   the client is active, and reflects coprocessor not
   present faults (Int 7) to the client.
o  Floating point emulation can be tested on a system with a
   numeric coprocessor by using this function to enable
   client handling of coprocessor exceptions and disable the
   coprocessor.
o  The client should use Int 31H Function 0212H to register
   an exception handler for coprocessor not present faults
   (Int 7) prior to setting the EMv bit with this function.
o  A client can determine the CPU type with Int 31H Function
   0400H, and the presence or absence of a coprocessor with
   Int 31H Function 0E00H.  The client should not draw any
   conclusions about the presence or absence of a
   coprocessor based on the CPU type alone.

Appendix B:  Error Codes and Messages



Nearly all Int 31H function calls can fail, either because
of client errors, unavailable resources, or internal host
problems.  Most failures due to client errors and all
failures due to unavailable resources are reported to the
client via error codes.  Some client errors, such as passing
an invalid pointer in a function call, may cause the host to
fault; the client can detect these events by installing an
exception handler.
Internal host errors are handled in a host-specific manner
and generally not reported to clients with an error code.
The only exception to this is the case when a host cannot
allocate internal resources. Any Int 31H function is capable
of returning error code 8010H to indicate this condition.
A DPMI 1.0 host signals an error by returning from a
function with the Carry flag set and an error code in AX.
If the error code has bit 15 clear (0), the DPMI host is
passing a DOS error code through to the client; for a list
of these error codes, consult a DOS technical reference.  If
the error code has bit 15 set (1), it is generated within
the DPMI host, and is interpreted according to the list
below.  All DPMI 1.0 hosts are required to check for the
error conditions listed in this specification, and must
return the error codes that are documented for each
function.
If Int 31H is invoked with an function number that is not
defined in this specification, the DPMI host will return the
"Unsupported Function" error code 8001H. The table lists all
defined error codes and their messages. Unused error codes
are reserved for the later versions of the DPMI
spcifications.

Err
or
Cod
eNameExplanation800
1HUnsupported
functionReturned in response to
any function call which is
not implemented by this
host, because the
requested function is
either undefined or
optional.800
2HInvalid stateSome object is in the
wrong state for the
requested operation.800
3HSystem integrityThe requested operation
would endanger system
integrity, e.g., a request
to map linear addresses
onto system code or data.800
4HDeadlockHost detected a deadlock
situation.800
5HRequest
cancelledA pending serialization
request was cancelled.801
0HResource
UnavailableThe DPMI host cannot
allocate internal
resources to complete an
operation.801
1HDescriptor
unavailableHost is unable to allocate
a descriptor.801
2HLinear memory
unavailableHost is unable to allocate
the required linear
memory.801
3HPhysical memory
unavailableHost is unable to allocate
the required physical
memory.801
4HBacking store
unavailableHost is unable to allocate
the required backing
store.801
5HCallback
unavailableHost is unable to allocate
the required callback
address.801
6HHandle
unavailableHost is unable to allocate
the required handle.801
7HLock count
exceededA locking operation
exceeds the maximum count
maintained by the host.801
8HResource owned
exclusivelyA request for
serialization of a shared
memory block could not be
satisfied because it is
already serialized
exclusively by another
client.801
9HResource owned
sharedA request for exclusive
serialization of a shared
memory block could not be
satisfied because it is
already serialized shared
by another client.802
1HInvalid valueA numeric or flag
parameter has an invalid
value.802
2HInvalid selectorA selector does not
correspond to a valid
descriptor.802
3HInvalid handleA handle parameter is
invalid.802
4HInvalid callbackA callback parameter is
invalid.802
5HInvalid linear
addressA linear address range
(either supplied as a
parameter or implied by
the call) is invalid.802
6HInvalid requestThe request is not
supported by the
underlying hardware.